Documentation visuelle

Prendre en main l'interface

Cette page montre l'application actuelle avec des vues rapprochées. L'objectif est simple : savoir lire une carte, ajouter une construction, relier deux modules, exécuter et exporter. Les captures viennent de l'application réelle ; elles ne sont pas des maquettes.

10 étapes
10 captures rapprochées
Interface actuelle

1 — Ouvrir un projet

Le plus rapide est d'ouvrir Examples → Simple → Imports. Le canvas affiche deux modules et une flèche. La barre du haut regroupe les commandes de fichier, d'affichage et d'exécution. Le statut en bas indique le zoom et la position de la vue.

Canvas Sapphire 3 avec les modules Library et App, une flèche de dépendance et une note. — **Le projet Imports.** Deux modules, une dépendance réelle et une note de présentation.

Une carte peut être déplacée, redimensionnée ou repliée. Le bouton Center the view replace les cartes dans le cadre. La molette zoome ; le clic-glisser déplace le canvas.

2 — Lire une carte Module

Une carte Module est une portée. Son titre est son nom. Les fonctions apparaissent en lignes. Le chevron ouvre les entrées, les étapes et le retour. Le badge pure signale une fonction sans effet de bord ni dépendance extérieure.

Carte Module Library avec la fonction square, son entrée value, ses étapes et son retour. — **Library.** La fonction `square` reçoit un entier et retourne une valeur.

Cliquez une ligne pour la sélectionner et ouvrir ses propriétés. Le bouton + ajoute une construction à l'endroit choisi ; il n'ajoute jamais un bloc au hasard.

3 — Lire une carte App

Une carte App est un module comme un autre, mais elle porte le programme de départ. Start here désigne le point d'entrée. Ici, main n'a pas de paramètre et contient une instruction Print.

Carte Module App avec la fonction main marquée Start here et une instruction Print. — **App.** Le point d'entrée est une propriété de la fonction, pas une convention de nom.

Un projet valide possède zéro ou un seul point d'entrée. Le moteur signale les doublons sans supprimer les données.

4 — Ajouter une construction

Le bouton + d'une carte ouvre le menu des constructions. Les familles sont à gauche : variables, fonctions, types, blocs, opérations natives, conditions, boucles et instructions. La colonne de droite propose les actions propres au module.

Menu d'ajout de Sapphire 3 avec les familles de constructions et les actions du module. — **Le menu +.** Choisissez une famille, puis une construction compatible.

Formulaire de création d'une fonction avec nom, type de retour, paramètres de type et entrées. — **Le formulaire.** Il demande uniquement les informations nécessaires à la construction.

Le formulaire ne crée rien tant que les champs requis ne sont pas valides. Si une valeur est refusée, le message apparaît dans le panneau et le document reste inchangé.

5 — Relier deux modules

Library exporte square. App l'importe et l'appelle. La flèche part du module exportateur et entre dans le module utilisateur. Elle n'apparaît que si une exportation est réellement référencée : un import inutilisé ne crée pas de dépendance.

Note de présentation du projet Imports expliquant que Library exporte square et que App l'importe. — **La note.** Une annotation de présentation reste hors du modèle logique.

Pour ajouter une dépendance, exportez une fonction depuis le module source, puis importez-la depuis le module utilisateur. Le moteur crée l'import et vérifie la signature.

6 — Vérifier les propriétés

Cliquez le titre d'un module pour ouvrir ses propriétés. Vous pouvez le renommer, voir les fonctions partagées avec les autres modules et choisir une fonction à importer. Le panneau ne modifie que le module concerné.

Panneau de propriétés du module Library avec son nom, ses exports et ses imports. — **Propriétés du module.** Le nom, les exports et les imports sont les seules informations publiques.

Sur une carte d'entrée — bouton, entier, décimal, texte, sélecteur RGB ou RGBA —, le sélecteur de fonction est placé dans le volet Configuration pliable de la carte. Il est replié par défaut ; un clic sur l'en-tête révèle la fonction liée sans encombrer l'aperçu.

7 — Exécuter

Run live exécute le programme et laisse le panneau Simulation suivre l'état. Le nombre d'étapes avance, la vitesse se règle avec le curseur, et Pause ou Stop reste accessible dans la barre. La sortie du programme apparaît dans le panneau Output.

Panneau Simulation de Sapphire 3 après une exécution terminée, avec le nombre d'étapes et la vitesse. — **Simulation.** L'état, les étapes et la vitesse sont visibles sans quitter le canvas.

Une exécution bornée reste disponible pour précalculer une trace finie. Le mode live est le mode normal pour suivre un programme en continu.

8 — Exporter

Transpile propose JavaScript, Python et un C expérimental. Le panneau montre le code généré, avec les boutons Copy et Export. Le code est produit depuis le même modèle logique, pas depuis une capture du canvas. Le C reste volontairement restreint : tableaux, classes, lambdas, ForEach, opérations natives et conversions y sont refusés. Le détail par cible est sur la page Transpilation.

Panneau de transpilation avec le code JavaScript généré depuis le projet visuel. — **JavaScript généré.** Les constructions prises en charge sont traduites ; les widgets graphiques restent hors périmètre. Les classes sont désormais transpilées en JavaScript et Python.

9 — Changer d'apparence

Theme règle l'apparence sombre ou claire et la palette. Le choix s'applique immédiatement. Le sélecteur de langue traduit l'interface, jamais les noms que vous saisissez ni les sorties du programme.

Menu Theme avec la bascule sombre ou clair et les palettes prédéfinies. — **Theme.** Une apparence commune à tous les thèmes, avec des palettes distinctes.

À retenir. Une carte est une portée, une ligne est une construction, une flèche est une dépendance réellement utilisée. Le moteur valide avant d'écrire : une erreur ne doit pas laisser le document dans un état intermédiaire.

10 — Étendre avec des plugins

Settings → Plugins installe un fichier local .sp3plugin. Un plugin peut ajouter des widgets déclaratifs, des opérations natives typées et des nœuds composites de niveau A. Les widgets apparaissent dans la quatrième colonne du menu de création — ouverte par un clic droit sur le canvas vide — lorsque des plugins sont actifs ; leur carte bascule entre le widget et sa définition déclarative JSON.

Le manifeste est validé avant installation : identifiants, permissions, dépendances, conflits, versions et opérations natives. Les entrées et sorties liées à une variable ou à une fonction sont tracées comme des dépendances depuis les modules fournisseurs. Un widget dont le plugin est absent conserve ses données et affiche un diagnostic.

À retenir. Un widget de plugin n'est pas un module source : sa vue code montre sa définition déclarative, pas un AST. Aucun eval, new Function, import de code tiers, marketplace ou backend distant n'est utilisé. Les permissions fichiers, réseau et API native sont déclarées mais refusées ; les opérations natives de plugin sont revalidées dans le run borné et le live, et le dashboard exporté les embarque.