Normalisation des modules

Principes généraux

Un module OpenOverlay est composé de trois fichiers principaux : manifest.json, overlay.js et admin.js. Cette page décrit les règles que chaque fichier doit respecter pour garantir la cohérence et la compatibilité entre modules.

• Un module ne doit jamais modifier le DOM ou l'état d'un autre module directement.
• L'état métier (série active, statut visible, etc.) est stocké dans la config serveur, jamais dans localStorage.
• localStorage est réservé aux données gérées par le core, toutes préfixées oo_ (oo_token, oo_channel, oo_broadcaster_id…). Un module ne crée jamais ses propres clés — et ne lit pas les clés core directement (utilise tools.token et tools.username dans render() si tu en as besoin côté admin).
• Pour partager un état temps réel entre overlay et dashboard (panel live, file d'attente…), utilise api.sendToAdmin(modId, payload) côté overlay et onOverlayMessage(payload) côté admin — jamais localStorage ni polling.
• Pour persister l'état d'un mod entre rechargements (ex : file active, scène en cours, score…), utilise api.saveState(modId, data) côté overlay ou tools.saveModState(modId, data) côté admin. La restauration au démarrage se fait via le hook onStateRestore(data, api), appelé par le core avant init() (système ≥ 1.45.0). Si le module utilise ces APIs, déclarer "minSystemVersion": "1.45.0" dans le manifest.
• Exception documentée : le mod Générique utilise localStorage pour persister les messages chat collectés pendant le stream. C'est le seul cas autorisé — les messages doivent survivre à un rechargement de l'overlay quand le dashboard n'est pas ouvert, et aucune alternative sans serveur n'existe. Toute autre utilisation de localStorage dans un mod est interdite.
• Toute commande chat expose un niveau d'accès configurable par le streamer.

manifest.json

Le fichier manifest décrit le module pour le système et pour le Store. Tous les champs listés ci-dessous sont obligatoires.

Champs obligatoires

Types de module

Le champ types est un tableau contenant une ou plusieurs des valeurs suivantes :

defaultConfig et permissions

Si le module expose une commande chat, la permission doit être configurable par le streamer. Deux cas :

Commande unique — ajouter ces champs dans defaultConfig :

{
  "command": "nom_commande",       // nom sans le !
  "commandPermission": "streamer"  // niveau par défaut
}

Commandes multiples (slots) — stocker les commandes dans un tableau d'entrées, chacune avec son propre champ permission. Pas de commandPermission global dans ce cas.

Les valeurs valides pour les permissions sont : "streamer", "moderator", "vip", "subscriber", "follower", "everyone".

overlay.js

Le fichier overlay s'enregistre via OO.Mods.register() avec un objet décrivant le module. Seule la propriété id est obligatoire ; toutes les méthodes sont optionnelles.

OO.Mods.register({
  id: 'mon_module',

  onStateRestore(data, api)            { /* état restauré avant init */ },
  init(api)                            { /* appelé au chargement */ },
  onConfigReload(api)                  { /* config rechargée */ },
  onChatCommand(cmd, args, api, sender){ /* commande chat reçue */ },
  onAdminMessage(data, api)            { /* message depuis admin */ },
  onTwitchEvent(type, event, api)      { /* événement Twitch */ },
  onFirstChatter(username, first, api) { /* premier message */ },
});

Méthodes disponibles

Objet api

L'objet api est passé à toutes les méthodes. Il expose :

OO.Mods — méthodes disponibles

En plus de OO.Mods.register(), l'objet OO.Mods expose les méthodes suivantes, utilisables depuis n'importe quel module overlay :

Permissions dans onChatCommand

Toujours utiliser api.checkPermission() pour vérifier l'accès, en lisant le niveau depuis la config :

onChatCommand(cmd, args, api, sender) {
  const cfg = api.config.mon_module;
  if (!api.checkPermission(sender, cfg.commandPermission ?? 'streamer')) return;
  // ...
}

Le broadcaster passe toujours, quelle que soit la valeur de commandPermission. Hiérarchie des niveaux :

Résolution d'assets

Deux origines possibles pour les fichiers (images, sons) stockés dans la config :

• Asset intégré — nom de fichier seul (ex : "follow.gif"), servi depuis /overlay/assets/gifs/ ou /overlay/assets/sounds/.
• Asset utilisateur — chemin préfixé user:// (ex : "user://mon-logo.webp"), résolu via api.resolveAsset(path).

function resolveGif(gif, fallback, api) {
  const file = gif || fallback;
  if (!file) return null;
  if (file.startsWith('user://')) return api.resolveAsset(file);
  return `/overlay/assets/gifs/${file}`;
}

Dans l'admin, utiliser createAssetField() (voir ci-dessous) — il gère automatiquement les deux origines.

admin.js

Le fichier admin s'enregistre via OO.Admin.register(). Les méthodes render et getCommands sont obligatoires.

OO.Admin.register({
  id: 'mon_module',
  render(config, container, helpers) { /* ... */ },
  getCommands(config) { return []; },
});

render(config, container, helpers)

config est l'objet de configuration complet de l'overlay. Accès à la config du module via config.[configKey]. container est l'élément DOM dans lequel le panneau est rendu.

Helpers disponibles

Pour le sélecteur de niveau d'accès des commandes, utiliser le helper exposé dans tools :

tools.permissionSelect('mon-module-perm', cfg.commandPermission ?? 'streamer')

Ce helper génère un <select> avec les six niveaux standards pré-rempli à la valeur courante.

getCommands(config)

Méthode obligatoire. Retourne un tableau des commandes chat exposées par ce module, utilisé pour alimenter le tableau de bord "Commandes chat". Retourner [] si le module n'expose aucune commande.

Commande unique :

getCommands(config) {
  if (config.enabled === false || !config.command) return [];
  return [{ cmd: `!${config.command}`, desc: 'Description courte', permission: config.commandPermission ?? 'streamer' }];
}

Commandes multiples (slots) :

getCommands(config) {
  if (config.enabled === false) return [];
  return (config.slots ?? [])
    .filter(s => s.command)
    .map(s => ({ cmd: `!${s.command}`, desc: s.label || '…', permission: s.permission ?? 'moderator' }));
}

Chaque entrée du tableau :

Framework CSS — modules

Le fichier admin/admin.css est chargé globalement dans le dashboard. Toutes les classes qu'il définit sont disponibles dans admin.js de n'importe quel module, sans import supplémentaire.

Utilitaires disponibles

Composants existants (§12 DESIGN_CHARTER)

Les composants de base du dashboard sont tous disponibles :

.card, .card-header, .card-title, .card-body, .card-body.grid, .card-section — .field, .field-inline, .hint, .span-full — .btn, .btn-primary, .btn-secondary, .btn-ghost, .btn-danger, .btn-sm — .toggle — .badge, .badge-green, .badge-red, .badge-muted, .badge-purple — .callout.info/tip/warn/plain — .table

Modificateurs de card

Utilitaires texte & couleur

Espacement

Préfixe mb- (margin-bottom), mt- (margin-top), ml- (margin-left) — valeurs disponibles :

mb-4/6/8/10/12/14/16/20  ·  mt-4/6/8/10/12/16/20  ·  ml-6/8/10

Également disponibles : .py-8 (padding vertical 8px), .m-0 (marge zéro), .min-w-90/100/120/220 (min-width).

Flex & visibilité

Composants de page

Règles d'usage

• ✅ Utiliser les classes ci-dessus directement dans le HTML généré par admin.js.
• ✅ Basculer la visibilité par toggle de classe : el.classList.toggle('hidden', !condition)
• ✅ Passer les couleurs dynamiques (issues de config) via CSS custom property et setProperty() :
  el.style.setProperty('--dot-color', color) (appelé en JS après rendu) + .ma-classe { background: var(--dot-color) }
  La valeur par défaut de la propriété est définie via setProperty() avant le premier rendu, jamais en fallback CSS.
• ✅ Ajouter des classes propres au mod en supplément (ex : .cp-enabled-label en plus de .text-muted).
• ❌ Ne pas utiliser style="..." dans le HTML généré — aucune propriété visuelle (couleur, taille, marge, visibilité) ne doit passer par un attribut inline.
• ❌ Ne pas utiliser de fallback dans var() dans les fichiers admin.css des mods (var(--x, fallback) est interdit). Si une valeur par défaut est nécessaire, la définir via setProperty() en JS avant l'affichage.
• ❌ Ne pas redéfinir les classes du framework dans mods/{id}/admin.css.
• ❌ Ne pas recréer des variantes locales (.mon-mod-list, .mon-mod-item…).

Système de zones

OpenOverlay fournit 9 conteneurs .oo-zone couvrant toutes les positions du sélecteur : top-left, top-center, top-right, middle-left, middle-center, middle-right, bottom-left, bottom-center, bottom-right. Un module qui affiche un widget positionnable doit :

• ✅ Appeler api.placeInZone(zoneId, element) dans init() et onConfigReload().
• ✅ Ne pas déclarer position: fixed dans overlay.css — le conteneur de zone gère le positionnement.
• ✅ Ne pas déclarer de propriétés top / right / bottom / left — elles seront ignorées dans un conteneur flex.
• ✅ Conserver z-index: var(--mod-z-{id}) si le module doit s'afficher devant d'autres éléments dans la même zone.

Variables CSS système dans overlay.css

L'overlay expose des variables CSS globales sur :root pour la coordination entre modules. Les utiliser plutôt que des valeurs figées :

• --oo-safe-bottom — espace réservé en bas de l'overlay par une barre système active (ex : ticker). Vaut 0px par défaut. Tout module avec un élément positionné en bas doit l'intégrer :
  #mon-widget { bottom: calc(16px + var(--oo-safe-bottom, 0px)); }
• --mod-z-{id} — z-index automatique géré par le système selon l'ordre des modules dans le dashboard. À utiliser dans overlay.css : z-index: var(--mod-z-mon-module, 10); — le fallback s'applique uniquement avant le premier chargement de config.

Si ton module occupe lui-même la zone basse (barre d'infos, bandeau…), il doit écrire --oo-safe-bottom en JS pour que les autres modules s'adaptent automatiquement :

document.documentElement.style.setProperty('--oo-safe-bottom', '40px'); // visible
document.documentElement.style.setProperty('--oo-safe-bottom', '0px');  // caché

Persistance d'état

Pour les modules avec un état métier significatif (file active, scène en cours, score…), le système expose /api/memory — un endpoint Netlify Blobs générique, un blob par utilisateur contenant { modId: data, … }.

APIs disponibles

Hook onStateRestore(data, api)

Appelé par le core avant init() avec les données sauvegardées — ou null. C'est l'endroit recommandé pour la restauration : pas d'appel réseau bloquant, état disponible dès init().

OO.Mods.register({
  id: 'mon_module',

  onStateRestore(data, api) {
    if (!data) return;
    this._score  = data.score  ?? 0;
    this._active = data.active ?? null;
    // Ne pas déclencher d'effets visuels ici — init() s'en charge
  },

  init(api) {
    // this._score et this._active sont déjà restaurés
    this._render(api);
  },

  _onAction(api) {
    this._score++;
    api.saveState?.('mon_module', { score: this._score, active: this._active });
    this._render(api);
  },
});

Messages admin → overlay

La communication du dashboard vers l'overlay se fait via sendToOverlay(data) (côté admin) et onAdminMessage(data, api) (côté overlay).

La propriété type est obligatoire et suit la convention [modId]_[action] :

// admin.js
sendToOverlay({ type: 'mon_module_update' });
sendToOverlay({ type: 'mon_module_reset' });
sendToOverlay({ type: 'mon_module_test', eventType: 'follow', user: 'TestUser' });

// overlay.js
onAdminMessage(data, api) {
  if (data.type === 'mon_module_update') this._start(api);
  if (data.type === 'mon_module_reset')  this._reset();
}

Checklist avant soumission

• ✅ manifest.json contient tous les champs obligatoires.
• ✅ version suit le format MAJOR.MINOR.PATCH et changelog est à jour.
• ✅ minSystemVersion est renseigné si le module dépend d'une API introduite dans une version précise du système.
• ✅ Chaque commande chat a un niveau d'accès configurable : via commandPermission (commande unique) ou via permission par entrée (commandes multiples / slots).
• ✅ overlay.js — les permissions sont vérifiées via api.checkPermission().
• ✅ Aucun usage de localStorage pour l'état métier.
• ✅ Les assets utilisateur sont résolus via api.resolveAsset().
• ✅ admin.js — getCommands() est implémenté et retourne [] quand enabled === false ou quand le module n'expose aucune commande.
• ✅ overlay.js — getCommands() aussi implémenté (au minimum { cmd, permission }) — alimente la commande d'aide : chuchotement au viewer + confirmation chat, sans jamais exposer la liste publiquement (système ≥ 1.30.0).
• ✅ Les niveaux d'accès utilisent tools.permissionSelect() et les valeurs standard.
• ✅ Les types de messages sendToOverlay suivent la convention [modId]_[action].
• ✅ Aucun attribut style="..." dans le HTML généré dynamiquement — aucune propriété visuelle ne passe par un inline style.
• ✅ Aucun fallback dans les var() des fichiers admin.css : var(--x) uniquement, valeur par défaut définie via el.style.setProperty() en JS.
• ✅ Les couleurs dynamiques (config streamer) passent par el.style.setProperty('--ma-var', valeur), pas par style="...".
• ✅ Le module ne modifie pas le DOM ou l'état d'un autre module.
• ✅ Si le module affiche un widget positionnable, il utilise api.placeInZone() et ne déclare pas position: fixed dans son overlay.css.
• ✅ Si le module affiche un élément positionné en bas hors zone (barre pleine largeur…), il utilise calc(Npx + var(--oo-safe-bottom, 0px)) dans overlay.css.
• ✅ Si le module occupe la zone basse (barre, bandeau…), il écrit --oo-safe-bottom sur document.documentElement quand il s'affiche/se cache.
• ✅ Si le module utilise api.saveState / onStateRestore, minSystemVersion est renseigné à "1.45.0" ou supérieur dans manifest.json.
• ✅ Les appels à api.saveState, api.loadState, api.sendToAdmin se font via optional chaining (api.saveState?.()) pour la rétro-compatibilité avec les instances plus anciennes.
• ✅ Le render() admin n'ajoute PAS de toggle « Activer le module » — le dashboard en affiche déjà un natif ; le module se contente de respecter config.enabled === false dans son runtime.
• ✅ Le ZIP de soumission au Store ne dépasse pas 10 Mo.