Paquets et dépôts

Un paquet est un dossier ou un zip avec un manifeste, un script et des ressources optionnelles. Un dépôt est un index JSON statique qui pointe vers des versions zippées. Rien ne s’installe automatiquement.

Contenu d’un paquet

extension.json
index.js           # script classique, pas un module ES
style.css          # optionnel
icon.svg           # optionnel, utilisé comme masque teinté
media/1.webp       # captures optionnelles, 16:9, 1280×720

extension.json

{
  "schema": 2,
  "id": "demo.hello",
  "name": "Hello",
  "version": "0.1.0",
  "subtitle": "Tuile de démonstration",
  "summary": "Affiche un message dans une tuile.",
  "description": "Description longue optionnelle.",
  "category": "Démonstration",
  "icon": "icon.svg",
  "color": "#769ac8",
  "entry": "index.js",
  "style": "style.css",
  "tileTypes": ["demo.hello.tile"],
  "screenshots": ["media/1.webp"],
  "engine": { "spark": ">=0.1" }
}
  • schema doit valoir 2.
  • id : au moins deux segments, minuscules, chiffres et tirets ; spark.* et official.* sont réservés ; 64 caractères max.
  • version : x.y.z numérique. name : 1 à 80 caractères.
  • entry : fichier relatif .js ou .mjs existant. style : fichier relatif .css existant.
  • icon : fichier relatif .svg existant, 32 Kio max. color : #rrggbb ou #rgb ; noms CSS et rgb() refusés.
  • tileTypes : 1 à 20 types, chacun préfixé par <id>., uniques.
  • screenshots : 0 à 8 fichiers .webp, .png, .jpg ou .jpeg existants.
  • certification est refusé dans un paquet importé. summary est plafonné à 400 caractères, description à 4 000.
  • Chemins absolus, .., antislashs et liens symboliques refusés. .git et node_modules ignorés.

Icône et teinte

L’icône est un masque CSS, jamais du markup interprété : le SVG fournit l’alpha, la couleur vient de currentColor. Aucun script du fichier ne s’exécute, et l’icône prend la couleur de l’extension dans le Store, le rail et la barre d’onglet.

Conséquence : Spark ne peut pas réappliquer l’épaisseur de trait. Dessiner le SVG en viewBox 24,fill="none", stroke="currentColor", stroke-width="1.7", et le tester à 16 px.

Bundle

(function () {
  const extensions = (window.SparkExtensions = window.SparkExtensions || {});

  extensions["demo.hello"] = function (runtime) {
    const React = runtime.React;

    function HelloTile() {
      return React.createElement("div", null, "Bonjour");
    }

    return {
      activate(api) {
        api.tiles.register({
          type: "demo.hello.tile",
          title: "Hello",
          view: HelloTile,
        });
        api.commands.register({
          id: "demo.hello.open",
          title: "Ouvrir Hello",
          tileType: "demo.hello.tile",
          run: () => api.tabs.openTile("demo.hello.tile"),
        });
      },
    };
  };
})();
  • L’hôte expose window.SparkRuntime = { React, jsxRuntime } et passe le même runtime à votre fabrique.
  • Ne jamais importer React par un module nu : utiliser le runtime de l’hôte.
  • Le paquet n’a pas d’API Tauri dédiée. Il partage la fenêtre principale et ses API globales.

Limites

LimiteValeur
Manifeste256 Kio
Fichiers400
Taille décompressée25 Mio
Profondeur8
Types de tuiles20
Icône32 Kio
Captures8
Zip téléchargé30 Mio
Index de dépôt2 Mio

Installation

registry_fetch(url)
  → téléchargement du zip (30 Mio max)
  → comparaison SHA-256
  → extraction contrôlée
  → validation de extension.json
  → staging → extensions/<id>/<version>/
  → extensions.json (version, chemin, source)
  → ExtensionManager.addEntry
  → activation

Une erreur de téléchargement, d’empreinte, d’extraction ou de manifeste laisse l’installation précédente intacte. L’état est écrit dans extensions.json avecversion, path et source (absent pour un import local). Une nouvelle version va dans un nouveau dossier ; l’ancien n’est pas supprimé automatiquement.

Index de dépôt

{
  "schema": 1,
  "name": "Mon dépôt",
  "updatedAt": "2026-11-21T22:00:00Z",
  "extensions": [{
    "id": "demo.hello",
    "name": "Hello",
    "publisher": "Demo",
    "summary": "Une ligne de description.",
    "category": "Démonstration",
    "versions": [{
      "version": "0.3.0",
      "url": "https://…/hello-0.3.0.zip",
      "sha256": "…",
      "size": 1307,
      "engine": ">=0.1",
      "publishedAt": "2026-11-21T22:00:00Z"
    }]
  }]
}
  • Une source est une URL HTTPS vers un fichier JSON statique. Jusqu’à 20 sources, enregistrées dans extensions.json.
  • En release, seul HTTPS est accepté ; en debug, http://127.0.0.1 et http://localhost sont tolérés.
  • Les index ne sont pas mis en cache sur disque : vérifier les recharge, un redémarrage les redemande.
  • La dernière version est choisie par comparaison numérique de x.y.z. Une version doit fournir version, url et sha256.
  • Le backend n’impose que schema: 1 et un tableau extensions ; le front normalise et écarte les entrées invalides.

Mise à jour

  1. Le dépôt publie une version supérieure.
  2. Vérifier recharge l’index.
  3. Mettre à jour télécharge le zip et vérifie son empreinte.
  4. L’extension active est désactivée, la nouvelle version installée, puis réactivée.
  5. Les tuiles et l’état de l’extension sont conservés.

Aucune installation automatique et aucun canal stable/beta pour l’instant. Les extensions intégrées ne sont jamais mises à jour par un dépôt.