Le PanelWave Player est disponible

Le PanelWave Player est la moitié ouverte de l’écosystème : une bibliothèque Angular sous licence MIT (Angular 20, 21 et 22) qui transforme un manifeste PanelWave en expérience de lecture complète, avec navigation, localisation, médias et commandes de lecture. Il est publié sur le registre public npm sous le nom @panelwave/player, en version 1.2.0 : npm install @panelwave/player suffit pour l’installer. Toutes les phases de fonctionnalités de base sont en place et les tests unitaires passent. Une suite de bout en bout Playwright, avec contrôles d’accessibilité axe-core, tourne sur navigateurs de bureau et mobiles. Et la documentation du lecteur décrit la bibliothèque telle qu’elle se comporte vraiment, défauts compris.

Le code source est sur github.com/panelwave/player, et une démo en ligne fait tourner les histoires d’exemple dans votre navigateur. Au programme de ce billet : ce que contient le lecteur, une intégration en cinq minutes, les points d’intégration qui comptent pour les hébergeurs, les nouveautés de la prochaine version et, en toute franchise, ce qui n’est pas encore fini. Seule l’API vous intéresse ? Allez directement à Entrées et sorties.

Ce que le lecteur affiche

Une œuvre est un ensemble de chapitres dont les cases forment les nœuds d’un graphe orienté. Le lecteur parcourt ce graphe en évaluant les conditions JSON Logic des arêtes, puis compose chaque case à partir de ses calques : images avec chargement différé et mise en cache, calques vidéo avec modes de lecture et déclencheurs de démarrage, calques de texte et de plugins isolés, et bulles dessinées par le moteur ComicBalloon. En vue case, on lit les cases une à une ; en vue page, elles sont composées en planches ; en vue canevas, on les parcourt sur un plan continu. La version 1.2.0 lit le format PanelWave jusqu’à la version 1.6 ; la vue d’ensemble donne le tableau complet des fonctionnalités.

De vrais embranchements, avec un vrai état

L’embranchement n’est pas un mode à part. Le moteur de déroulement rassemble les arêtes sortantes de la case courante, évalue leurs conditions à partir du stock de variables et retient la correspondance de plus haute priorité. Les changements de variables portés par une arête s’appliquent au moment où on l’emprunte, et revenir en arrière restaure à la fois la position et l’état. Quand plusieurs chemins sont ouverts, le bouton Choices de la barre d’outils laisse le public choisir, chaque option portant le texte de son arête. Les variables vivent dans cinq portées (global, chapitre, page, session, persistant) ; elles sont typées et validées à chaque écriture, et la portée persistante survit aux rechargements grâce à localStorage. Les conditions échouent en mode fermé : une erreur d’évaluation vaut faux, et une arête sans condition reste toujours empruntable. Le fonctionnement est détaillé pas à pas dans État, conditions et navigation, et le stockage dans Sauvegarder la progression.

Les définitions de variables du manifeste alimentent le stock : valeurs par défaut, types, plages et indicateurs de lecture seule s’appliquent dès la première case. La fenêtre de réglages a en plus un onglet Variables : les définitions marquées publiques y apparaissent, chacune avec un éditeur adapté à son type. Un créateur peut ainsi exposer délibérément des interrupteurs narratifs à son public (Fenêtre de réglages).

Trois modes d’affichage, dont le canevas infini

La vue case et la vue page existent depuis les premières phases. La vue canevas, arrivée avec le format 1.4, place toutes les cases d’un chapitre sur un même plan et fait glisser une caméra de l’une à l’autre le long du graphe narratif : trajectoire directe, en arc ou par points de passage définis, avec un profil de zoom maintien, recul ou plongée. Comme dans une application de cartographie, la moindre action interrompt le glissement. Seules les cases proches de la caméra sont montées, douze au maximum quelle que soit la taille du chapitre, et les modes de révélation gardent les embranchements secrets voilés jusqu’à ce que le parcours y mène. La sémantique de navigation ne change pas : « suivant » interroge toujours le moteur de déroulement. Détails dans Vue canevas et la référence du format.

Cases vidéo et moteur audio à quatre bus

Les calques vidéo proposent trois modes de lecture (une fois, en boucle, ping-pong), deux déclencheurs (à l’affichage, au clic) et, en vue page, l’enchaînement : les vidéos d’une page se lisent l’une après l’autre, dans l’ordre de lecture. La lecture automatique tient compte de la vidéo : au lieu de suivre une horloge, elle attend la fin d’un passage complet, et un chien de garde force l’avancement si une source ne se termine jamais. Jamais plus d’une vidéo sonore à la fois. Le moteur audio mixe quatre bus (ambiance, musique, voix off, bruitages), chacun avec son volume et ses fondus, et respecte la politique de lecture automatique des navigateurs. Voir Audio, la référence du format vidéo et Lecture automatique.

Le moteur de rendu ComicBalloon

Les bulles sont de vraies bulles de BD, dessinées en SVG par une classe TypeScript indépendante de tout framework. Le texte est mesuré ; le corps est un squircle (ou un nuage de pensée, une explosion de cri, un chuchotement en pointillés, un cartouche de narration à angles vifs, un cartouche à bords coupés, ou un connecteur) ; la queue fait partie du contour ; et la mise à jour ne coûte presque rien. Au total : dix types de bulles, des bosses et des pointes déterministes, un effet de bordure masquée pour les bulles qui se fondent dans le bord de la case, et des polices de lettrage sous licence libre fournies avec le paquet. Le style se résout en cascade : réglages par défaut de l’œuvre, surcharge par personnage, préréglage nommé, puis surcharge par bulle. Comme le CMS intègre ce même moteur, le public voit exactement le lettrage du créateur. Moteur de rendu des bulles détaille la chaîne de rendu ; Bulles en décrit le côté manifeste.

Zones interactives et variantes de case, en action

Les zones interactives qu’un créateur dessine fonctionnent dans le lecteur. Les régions rectangulaires, circulaires et polygonales deviennent des cibles cliquables, au contour qui pulse doucement (sauf avec les animations réduites). En activer une déclenche son action : aller à une case avec une transition, définir des variables, ouvrir les bonus sur un élément précis, afficher une fenêtre localisée ou transmettre l’événement à un plugin. Les zones interactives sont accessibles au clavier et annoncent leur libellé aux lecteurs d’écran. Chaque clic remonte comme événement de mesure d’audience, avec des coordonnées normalisées : c’est ce qui alimente la carte de chaleur des clics du CMS. Les variantes de case sont elles aussi résolues à l’exécution : la première variante dont la condition est vraie remplace le contenu de la case, et le tout est réévalué à chaque changement de variable. Quand une œuvre propose des alternatives, le bouton Alt de la barre d’outils les fait défiler. Voir Zones interactives et Variantes.

Une localisation sans rechargement

Chaque chaîne visible du public est une LocalizedString indexée par locale BCP-47, et les médias peuvent avoir des variantes par langue. Le lecteur résout les deux via une chaîne de repli (locale exacte, langue de base, langue par défaut de l’œuvre, sa langue de base, première disponible) et change de langue instantanément, depuis la fenêtre de langue de la barre d’outils ou avec la méthode changeLocale. L’interface du lecteur lui-même se traduit à part, via des fichiers ngx-translate servis par votre application ; l’anglais et l’allemand sont fournis. Localisation couvre les deux niveaux et la chaîne de repli.

Performances sur réseaux lents et appareils modestes

Trois mécanismes font le travail. D’abord, une file de préchargement par priorité, à concurrence limitée : elle s’adapte à la Network Information API, s’arrête complètement quand l’économiseur de données est activé, et préchauffe les illustrations des arêtes sortantes de la case courante. Ensuite, un cache d’images LRU qui décode hors du fil principal avec createImageBitmap, dans un budget de 100 Mo. Enfin, la sélection de variante : pour chaque case, chaque mode d’affichage et chaque niveau de zoom, elle choisit le plus petit échelon d’image qui couvre la largeur réellement affichée, par paliers de 256 pixels et uniquement à la hausse. Sur un téléphone, on télécharge de petits échelons WebP ; avec un zoom avant sur un écran 4K, on reçoit l’encodage complet. Tous les composants sont en OnPush. Toute la mécanique est détaillée sur la page Performances.

L’accessibilité par défaut

Chaque bouton de la barre d’outils porte un aria-label traduit, et les boutons à bascule exposent aria-pressed. La zone d’affichage est une région étiquetée, activable au clavier ; en vue page, les cases peuvent recevoir le focus, et les zones interactives font partie de l’ordre de tabulation. Les animations réduites s’activent à la demande du système d’exploitation, de l’interrupteur dédié dans la fenêtre de réglages ou de l’entrée reducedMotion de l’hébergeur : les transitions animées sont alors coupées, et les vidéos qui démarrent à l’affichage passent en lecture au clic. Les contrôles axe-core de la suite Playwright tournent en intégration continue. Voir Accessibilité.

Paywalls, mesure d’audience et plugins

Le lecteur ne traite jamais de paiement. Le manifeste déclare ce qui est réservé, par œuvre, chapitre, case ou bloc de bonus. Le lecteur évalue ces règles à partir d’un instantané des droits d’accès, que votre application lui transmet ou qu’il récupère une fois au démarrage auprès de votre point de terminaison. Face à un contenu verrouillé, le public voit une surcouche de paywall avec les options Buy et Subscribe de la règle ; les cases d’aperçu gratuit restent ouvertes, et un contrôle d’âge intégré couvre les contenus soumis à une classification d’âge. Le choix effectué remonte à votre application par la sortie paywallAction. Pour décider case par case depuis votre propre service, il existe aussi un adaptateur de droits d’accès. Paywall et droits d’accès explique quelle intégration choisir.

La mesure d’audience respecte le consentement dès la conception : si le manifeste l’exige, rien n’est enregistré avant le consentement ; seuls les types d’événements autorisés sont conservés ; les événements à haute fréquence sont temporisés ; et les lots partent vers le point de terminaison indiqué par le manifeste. Les hébergeurs peuvent aussi se passer de ce service et envoyer les sorties du shell vers leurs propres statistiques. Voir Mesure d’audience.

Les plugins sont des pages web ordinaires, chargées dans des iframes isolées. Ils dialoguent avec l’hôte par postMessage, selon un modèle de permissions à douze capacités, avec des états de cycle de vie et un protocole documenté. Une case peut aussi intégrer directement un plugin sous forme de calque, par exemple pour une visionneuse à 360 degrés. Voir Plugins.

L’intégrer en cinq minutes

Le composant à intégrer est le shell du lecteur. Il est autonome (standalone) : aucun module à importer. Ajoutez provideHttpClient et un chargeur TranslateModule à la configuration de votre application, incluez une fois la feuille de style des polices de bulles, puis indiquez au shell l’URL de votre manifeste (ou récupérez vous-même le JSON et liez-le comme objet). Un exemple complet et fonctionnel, avec un manifeste minimal valide, vous attend sur Démarrage rapide : intégration.

À partir de là, le shell fournit tout ce dont un site de lecture a besoin : initialChapterId et initialPanelId pour reprendre la lecture au bon endroit ; panelChange (avec l’identifiant de la case) et chapterChange pour enregistrer la progression et créer des liens profonds ; navigationAttempt pour les interstitiels ; error pour votre propre interface de secours ; et les méthodes publiques setVariable et changeLocale. Les entrées comme la langue, la lecture automatique et les animations réduites s’appliquent en direct, œuvre ouverte. initialVariables injecte des faits connus de l’hôte par une voie privilégiée, que même les définitions en lecture seule acceptent. Le public peut poser un marque-page depuis la barre d’outils, et l’œuvre s’y rouvre. La reprise automatique « reprendre où vous en étiez » relève volontairement de l’hôte : Sauvegarder la progression en donne une implémentation localStorage complète, prête à copier. Les réglages par défaut pilotés par le manifeste (visibilité des bulles, rythme de la lecture automatique, préréglages typographiques, stratégie de préchargement) sont listés sous Configuration.

Ce qu’apporte la prochaine version

La prochaine version npm est déjà fusionnée : c’est elle que le public voit aujourd’hui sur read.panelwave.org et dans l’aperçu du CMS. Les points forts :

Chaque nouveauté porte la mention « from the release after 1.2.0 » dans la documentation du lecteur : vous voyez d’un coup d’œil ce que fait la version installée chez vous.

• Format 1.7. Les chapitres sans arêtes suivent simplement l’ordre de leurs cases. Les cases encore verrouillées arrivent du serveur sous forme d’emplacements réservés. Les zones interactives peuvent afficher leur libellé comme un bouton : les options d’un choix restent visibles même quand l’illustration ne les montre pas. Et les bulles acceptent un lettrage de n’importe quelle couleur.
• Une vue page adaptée à l’écran. Le lecteur choisit la mise en page que le créateur a prévue pour l’appareil (mise en page téléphone sur un téléphone, mise en page grand écran sur un écran 4K) et en change quand la fenêtre est redimensionnée. Le lettrage suit l’échelle de la page sans jamais descendre sous une taille lisible.
• Une couverture et un début de lecture clair. Une œuvre s’ouvre sur sa couverture, puis en vue page. Chaque page et chaque case a sa propre adresse à partager, et face à un choix, « suivant » laisse choisir au lieu de trancher d’office.
• Plein écran, animations et plus encore. Un bouton plein écran, des animations de calques par images clés et des mouvements de caméra dans une case, plusieurs couvertures alternatives, et une gestion plus stricte du paywall : une case verrouillée le reste aussi en vue page et en vue canevas.

Pour les contributeurs

Pour travailler sur la bibliothèque elle-même, la documentation propose un parcours dédié aux contributeurs : Architecture pour l’organisation de l’espace de travail, la gestion de l’état et le flux de données du manifeste au rendu ; Services principaux pour les services de manifeste, d’état, de stock de variables, de moteur de déroulement, d’actions des zones interactives, de cache d’images, de préchargement, d’audio, de vidéo, de mesure d’audience et de droits d’accès, et leurs interactions ; Composants pour le shell, la zone d’affichage, les moteurs de rendu des calques, les surcouches, les fenêtres modales et la barre d’outils ; et Développement pour l’installation, les suites Jasmine et Playwright, le lint et le build de production.

Ce qui reste à faire

Mieux vaut l’apprendre ici que dans une console :

Chacun de ces points est suivi et documenté à l’endroit précis où vous le rencontreriez.

• Commentaires et partage : interface seulement. Le tiroir de commentaires et la fenêtre de partage fonctionnent côté public, mais le stockage des commentaires revient à l’hôte (Commandes de la barre d’outils).
• Mode manga et contraste élevé : enregistrés, pas encore appliqués. La fenêtre de réglages mémorise le choix, mais la mise en page ne s’adapte pas encore.
• Pas de reprise automatique. Le lecteur restaure le marque-page, pas la dernière case lue. Reprendre là où l’on s’est arrêté relève de l’hôte, avec une recette toute prête dans la documentation.

Essayez-le, intégrez-le, cassez-le

L’application de démo du dépôt sert d’intégration de référence et peut charger n’importe quel manifeste depuis une URL : une œuvre publiée en lien d’aperçu depuis le CMS s’y ouvre directement. Vous construisez quelque chose avec le lecteur, ou il affiche mal un manifeste ? Commencez par le suivi des tickets et la documentation du format. Le format est ouvert, le lecteur est sous licence MIT, et le rendu de l’aperçu du CMS, c’est exactement cette bibliothèque.