Lancer une appli ou un widget

kapp.apps appartient au SDK commun des iframes applis et widgets, pas au helper des plugins HTML. Il lance une cible et attend son résultat. Pour appeler une fonction d’une exécution déjà disponible, lire services.

API	Résultat
await listApps()	Applis lançables sur l’overlay, avec slug, arguments et contrat de sortie.
await listWidgets()	Widgets lançables, ID local au channel et arguments.
await list()	Réunit les deux listes avec type: 'app' ou 'widget'.
await runApp(slug, args, options)	Lance une appli installée compatible avec l’overlay. Une instance déjà présente peut donner busy.
await runWidget(id, args, options)	Lance un widget ; plusieurs exécutions peuvent coexister.
await run(target, args, options)	Cible {type: 'app', slug} ou {type: 'widget', id}.

Les listes peuvent rejeter. Les lanceurs ne lèvent pas d'exception : ils résolvent {resolved: true, data} (la valeur passée par la cible à finish(result)) ou {resolved: false, reason}. Toujours lire resolved. Raisons observées, sans liste fermée :

Contexte	Raisons
Communes	aborted ou la raison passée à abort(), no_result (finish() sans valeur), timeout, erreurs de validation des arguments (argument '…' is required, … must be of type …), invalid_target (cible de run mal formée), invalid_response
runApp	busy (une instance tourne déjà), not_installed / not_found, unsupported_display_mode (affichage incompatible, par exemple une app exclusivement en popout), invalid_output (résultat contraire au run-output déclaré)
runWidget	not_found (ID inconnu sur ce channel), disabled. Plusieurs exécutions peuvent coexister ; sortie non typée

Formes des listes : listApps() renvoie {slug, title, version, kind, arguments: [{name, key, type, required, separator}], output: {type, description}} ; listWidgets() renvoie {id, name, enabled, arguments: [{name, key, type, description, required}]} ; list() concatène les deux avec type: 'app' | 'widget', la forme attendue par run. Un ID de widget reçu en chaîne (formulaire, préférence) est converti par run.

Découverte et appel

Extrait utilisable après démarrage SDK, dans le script métier d’une appli ou dans executeWidgetFunction d’un widget :

const candidates = await kapp.apps.listApps();
const picker = candidates.find(app => app.kind === 'pick-string');
if (!picker) throw new Error('Aucun sélecteur installé');
const result = await kapp.apps.runApp(picker.slug, {options: ['rouge', 'bleu']}, {timeoutSeconds: 30});
if (!result.resolved) throw new Error(`Sélection non confirmée : ${result.reason}`);
const choice = result.data;

Ne pas lancer arbitrairement la première cible de la liste. Un ID de widget n’est pas portable entre channels. Les arguments doivent être déclarés par la cible ; les clés libres ne deviennent pas automatiquement ses arguments. Lire arguments.

Résultat et durée

La cible renvoie explicitement await kapp.finish(result) ; sans résultat, l’appelant peut recevoir no_result. Le widget qui doit répondre utilise donc cette exception à sa fin automatique. Une appli peut déclarer run-output ou kind, et laisser le streamer choisir une cible par une préférence runTarget : voir app-to-app, réservé au parcours appli. Un widget n’a pas ce manifeste.

timeoutSeconds est entier, de 1 à 1 800, défaut 120. Le SDK utilise un budget total pour les lanceurs, incluant file et réponse. Le timeout termine uniquement l'attente de l'appelant, sans fermer l'appli lancée ; il n’est pas une preuve que la cible n’a rien fait, ni une instruction de la relancer. Une fermeture du caller ne garantit pas un rollback des effets de la cible.

Une appli appelante déclare apps:run pour les listes comme les lancements, quelle que soit la cible. Un widget n’invente pas de scopes de manifeste. Les contrôles d’installation, d’activation, d’accès et de disponibilité restent applicables. Voir permissions.