Fichiers sp3

Fichiers .sp3 et workspaces

Workspace

Un workspace est un dossier choisi par l’utilisateur :

mon-projet/
  workspace.sp3
  images/
  backups/

• workspace.sp3 est le document interne, au format JSON UTF-8 non compressé.
• images/ contient les images liées par une référence relative ; une image peut aussi être intégrée en Data URL.
• backups/ conserve jusqu’à trois sauvegardes de secours lors d’un enregistrement direct.

Le document interne reprend l’enveloppe suivante :

{
  "application": "Sapphire 3",
  "workspaceVersion": 3,
  "project": { "formatVersion": 1, "id": "workspace", "modules": [], "nodes": [] },
  "presentation": {
    "cards": [],
    "camera": { "x": 0, "y": 0, "zoomLevel": 0 },
    "selected": null
  },
  "exercise": null,
  "dashboard": null
}

• project : source logique complète, identifiants, références, types, point d’entrée.
• presentation : cartes, positions, tailles, pliage, notes, images, vue, sélection. Une carte pluginWidget porte pluginId, widgetId, pluginVersion, properties, state, bindings et éventuellement pluginWidgetView (widget par défaut, definition pour la définition JSON).
• exercise : manifeste optionnel (voir Exercices).
• dashboard : configuration optionnelle de l’export Web Dashboard.
• Les plugins installés et leurs préférences sont hors du workspace, dans la préférence locale sapphire-plugins. Un workspace ne déclenche jamais l’installation automatique d’un plugin ; une carte de plugin absente conserve ses données.
• AST, diagnostics, index et caches sont recalculés, jamais enregistrés.

Versions

• workspaceVersion courant : 3.
• Versions 1 et 2 migrées à la lecture vers la version 3 : generic → typeParameters, retrait de screenScale, images liées, workspace en dossier.
• Version future ou malformée : refusée sans remplacer le document.
• project.formatVersion reste 1.

Autosauvegarde

• Le document interne du workspace courant est réécrit après chaque modification, avec un délai de 500 ms pour regrouper les actions.
• Aucune écriture pendant un dialogue natif ou une importation en attente.
• Un document jamais enregistré mais non vierge est protégé dans sapphire3-recovery/, dans le répertoire de données persistant.
• La copie est restaurée au lancement, puis effacée après sauvegarde, « Enregistrer sous », nouveau document ou remplacement confirmé.
• Une copie illisible est supprimée sans bloquer la réouverture du dernier workspace.

Sauvegardes de secours

À chaque enregistrement direct, jusqu’à trois générations précédentes dans backups/ :

backups/workspace.backup-1.sp3
backups/workspace.backup-2.sp3
backups/workspace.backup-3.sp3

Une copie impossible n’annule pas la sauvegarde ; elle est signalée. Les sauvegardes ne tournent pas à l’autosauvegarde ni lors d’un « Enregistrer sous ».

Ouvrir, importer, exporter

• Open workspace : dialogue natif de dossier, confirmation de remplacement.
• Import .sp3 / .json : accepte un document workspace ou une source logique JSON v1 seule, avec disposition initiale.
• Save / Ctrl+S : écrit le document interne du workspace courant.
• Save as… : nouveau chemin sans écraser l’existant.
• New workspace : document vierge.
• Export ZIP : archive du workspace avec le document interne et les images liées.
• Export SVG : vue d’ensemble dépliée, sans modifier le document.
• Export PNG/JSON d’un nœud : depuis le panneau de propriétés.

Les cinq workspaces récents et le dernier dossier sont mémorisés localement. Un chemin inaccessible est oublié.

Validation

Avant tout remplacement :

• structure des modules et nœuds ;
• identifiants uniques ;
• géométrie des cartes ;
• cohérence carte/module ;
• vues de widgets ;
• contrats ;
• manifeste d’exercice et starter ;
• configuration dashboard ;
• JSON sérialisable sans perte.

Un programme sémantiquement incomplet peut être restauré ; le moteur conserve ses diagnostics.

Limites

• Taille maximale du document interne : 20 Mio.
• Pas de fusion de documents.
• Pas de migration automatique des versions futures.
• Les menus, formulaires non validés, gestes et scrolls internes ne sont pas sauvegardés.
• Les tests d’exercice et les tests de correction restent visibles dans le fichier.