Plugins

Plugins

Le Plugin SDK local permet d’ajouter des widgets, des opérations natives et des nœuds composites sans modifier le moteur. Un plugin est un manifeste JSON déclaratif .sp3plugin ; aucun code tiers n’est importé ou exécuté.

Installation

Settings → Plugins importe un fichier local .sp3plugin, affiche ses métadonnées, ses capacités et ses permissions, puis permet de l’activer, de le désactiver ou de le désinstaller. Un plugin installé et activé est résolu au démarrage avec ses dépendances, ses conflits et sa compatibilité d’hôte.

Les plugins sont stockés hors du workspace, dans la préférence locale sapphire-plugins. Un workspace ne déclenche jamais l’installation automatique d’un plugin.

Widgets

Un widget est une carte pluginWidget de présentation :

• renderer déclaratif whitelisté (stack, row, text, value, bar, led, input, button, divider, spacer) ;
• propriétés configurables, état persistant et interactions slider/bouton ;
• entrées typées liées à une variable visible ;
• sorties typées liées à une fonction (T) -> void ;
• bascule entre le widget et sa définition déclarative JSON en lecture seule ;
• liens de dépendance depuis les modules qui fournissent les variables et fonctions liées.

Un widget de plugin n’a pas de module source ni d’AST. Si le plugin est absent ou désactivé, la carte conserve ses données et affiche un diagnostic.

Opérations natives

Une opération native de plugin est typée et validée avant exécution. Le manifeste décrit ses paramètres, son retour, sa pureté ou ses effets, une expression d’implémentation sûre et, éventuellement, des émetteurs JavaScript/Python. Le registre dynamique est consulté après les opérations natives intégrées.

Les opérations sont revalidées dans le run borné, le Run live et les Workers. Le C expérimental les refuse (TRANSPILE_C_UNSUPPORTED). Une opération sans backend disponible produit un diagnostic explicite (TRANSPILE_EXPRESSION_UNSUPPORTED).

Composites

Un composite de niveau A insère un brouillon natif dans le module courant avec des trous à remplir. L’insertion est atomique et réutilise l’AST existant. Les nœuds sémantiques de niveau B ne sont pas opérationnels.

Dashboard exporté

Le dashboard HTML autonome embarque les widgets de plugin visibles, leurs définitions, les manifestes actifs et les opérations natives. Les entrées utilisent les frames de variables du Run borné et du live ; les sorties déclenchent la fonction liée. Un plugin absent produit un panneau de diagnostic sans retirer les données.

Sécurité et limites

• Aucun eval, new Function, import de code tiers, marketplace ou backend distant.
• Permissions explicites : ui.widgets, workspace.widget-state, engine.native-operations, engine.composites.
• Les permissions fichiers, réseau et API native sont déclarables mais refusées (PLUGIN_PERMISSION_UNSUPPORTED).
• Les widgets ne peuvent pas exécuter de composant React ou de JavaScript tiers.
• Une sortie de widget est liée à une fonction (T) -> void ; pas de callbacks multiples.
• Le niveau B sémantique reste hors périmètre.

Exemples et tests

Les exemples locaux sont examples/plugins/voltmeter.sp3plugin (widget), clamp.sp3plugin (opération native CLAMP) et between.sp3plugin (composite).

pnpm plugin:test
pnpm plugin:build
pnpm plugin:pack

La documentation détaillée se trouve dans docs/sdk/plugin-sdk.md et le rapport de capacités dans docs/PLUGIN_CAPABILITIES.md.