Pièges spécifiques aux applis

Pièges transverses (V1→V2, async, noms de services, arguments chat) : voir common/PITFALLS.md. Ci-dessous, ce qui est propre au runtime appli.

Cycle de vie

kapp.finish() est explicite. Une appli ne se termine pas quand script.js finit de s'exécuter (contrairement au widget). Si tu oublies finish(), l'appli reste ouverte et les rewards accumulées ne sont jamais envoyées (sendRewards() est appelé par finish()).
Pas de window.executeAppFunction : ton code tourne dans script.js après l'event AppliLoaded (généralement une IIFE (async () => { ... })()).
kapp.display() affiche la fenêtre ; pour une appli backtask sans UI, tu n'en as pas besoin.
Nettoyage avant sortie : kapp.onBeforeFinish(fn) / kapp.onBeforeAbort(fn) / kapp.onBeforeExit(status, fn) (handlers sync ou async, tous attendus).

kapp.preferences = config du streamer (définie via preferences.config.js, éditée dans le dashboard). Lecture via get(path) / global prefs. prefs n'est pas réactif : relis après un set.
kapp.dataStorage = état global de l'appli (un seul jeu de données par app+channel). set(data) écrase tout (pas de merge auto) → relis avec get() et fusionne toi-même.
kapp.userDataStorage / user.getAppData() / user.setAppData() = état par viewer. Lève une erreur (AppMethodError) hors contexte appli.
kapp.logsStorage = historique empilé (append-only via add()), pour scores/événements ; pas pour de l'état mutable.
Pas de données importantes dans localStorage, sessionStorage ou IndexedDB. L'origine du document peut être Kappapps, localhost ou le CDN selon le contexte et évoluer entre deux versions ; les plugins et prefs panels sont en plus sandboxés. Ces stockages navigateur peuvent donc être absents ou sembler remis à zéro. Persiste l'état métier avec kapp.dataStorage / kapp.userDataStorage, et la configuration avec kapp.preferences.

preferences.config.js est compilé en config/preferences.config.json par le HUB (transpile). N'édite pas le .json à la main, il sera écrasé.
Les chemins de get() suivent l'arbre des groupes : kapp.preferences.get('global.example.exempleItemTypeString').
get(path) renvoie undefined si le chemin n'existe pas — garde tes valeurs par défaut.
Le default d'un item mediaFile ne peut référencer QUE la bibliothèque publique Kappapps : default: { library: '<slug>' }. Une clé media (id de fichier channel) en default = CRIT à la validation ; un slug inexistant = CRIT ; un asset dépublié = WARN. La valeur hydratée ({file, volume, position}) se joue telle quelle avec kapp.medias.playMedia(pref).

kapp.rewards.winner(user) / loser(user) accumulent localement ; rien n'est envoyé tant que sendRewards() (déclenché par finish()) n'a pas tourné.
Si un viewer est marqué winner et loser, la dernière valeur écrite gagne.

text(key, args) (global) = kapp.textset.get(key, args). Une valeur de textset.js peut être une string ou une fonction args => string (voir reference/i18n.md).
Si la clé est absente, text() renvoie la clé elle-même (pas d'erreur) — vérifie tes clés.

Contrairement au widget, prefs et text() sont injectés en appli. Ne copie pas du code widget qui les évite.

Sandbox opaque (allow-scripts sans allow-same-origin) : ton origine y est 'null' — pas de localStorage/cookies/accès au parent. Tout passe par window.KappappsPrefs (voir reference/prefs-panels.md).
Entrée HTML obligatoire : prefs-panel-index et wuOptions.source pointent vers un .html/.htm, jamais directement vers un .js. La plateforme ne génère pas de coquille HTML.
CSP durcie script-src 'self' https://kappapps.app : seul le SDK prefs officiel peut venir de Kappapps ; aucun autre CDN ni <script> inline. Le JS de l'app vit dans un fichier séparé chargé avec un chemin relatif.
Remount à chaque sauvegarde du formulaire de préférences (nouvelle iframe, nouveau onReady) : ton état JS en mémoire ne survit pas — persiste ce qui compte via KappappsPrefs.setValue(), jamais dans une variable globale.
watch(paths) = préfixe de segment : observer un chemin de groupe couvre déjà tous ses descendants, inutile de lister chaque sous-champ.
Un WU customPanel n'a aucune valeur propre : ne t'attends pas à lire quoi que ce soit à son propre chemin.

Si l'app utilise un bundler ou un transpileur, configure cli-config.json avec "runtime": { "root": "dist" } : les sources restent dans le workspace et seul le runtime généré est servi et publié.
dist/ doit fonctionner seul : index.html, JS/CSS compilés, assets et config nécessaires. Aucun fichier publié ne doit dépendre de src/, de node_modules/ ou d'un chemin situé hors de dist/.
Préfère un bundle navigateur autonome quand le découpage en modules ou chunks au runtime n'apporte rien. Ces imports restent supportés, mais ils multiplient les fichiers et requêtes à servir ; conserve-les seulement quand leur chargement différé a un bénéfice réel.
Ne modifie jamais dist/ à la main. Lance explicitement le build avant prepare_preview, un diff ou un push : le DEV HUB ne lance pas les commandes npm du projet automatiquement.

Chaque fichier image chargé produit une requête. En production, les fichiers propres à l'app peuvent être servis directement par le CDN ; en local, ils viennent du DEV HUB. Ne dépends donc jamais de l'origine courante ni d'un chemin racine Kappapps pour les retrouver : utilise des chemins relatifs au runtime publié ou les URLs fournies par le SDK.
Regrouper de nombreuses images reste une bonne pratique web : cela réduit le nombre de requêtes navigateur et de fichiers à charger, même lorsque Bunny sert directement les octets.
Dès qu'une appli contient beaucoup d'images, utilise Créer un atlas dans l'onglet Assets du DEV HUB ou le tool MCP create_image_atlas pour réduire les requêtes. Voir reference/image-atlases.md.
Ne valide jamais un plugin en ouvrant seulement son localhost : sans le shell de prepare_preview, il manque le bridge, les JWT et les sockets, et le test peut être faussement vert.
Un atlas ne réduit pas automatiquement le poids : analyse-le avec la qualité WebP, le resize et le profil adaptés, et traite l'avertissement s'il devient plus lourd.
Le créateur d'atlas conserve toujours les sources. Après migration du code, supprime-les ou exclue-les du push ; sinon le gain de distribution sera incomplet.