create-snapify-app 0.0.0-stage → 1.1.0

package/template/apps/developers/src/pages.tsx

@@ -0,0 +1,1587 @@
+/**
+ * Snapify Developers — contenu de la documentation
+ * © 2026 NOVALABS WEB DESIGN — Tunisie
+ */
+import { useEffect, useState, type ComponentType } from 'react';
+import { Link } from 'react-router-dom';
+import { C, Code, H2, H3, MARKETPLACE_URL, NextLink, Note, SDK_DOWNLOAD_URL, Steps, Table } from './ui';
+
+export const API_VERSION = '1.3.0';
+
+export interface DocPage {
+  slug: string;
+  section: string;
+  title: string;
+  description: string;
+  keywords?: string;
+  Body: ComponentType;
+}
+
+type MpSettings = { commissionBps: number; developerFeeLabel: string };
+
+function useMarketplaceSettings() {
+  const [s, setS] = useState<MpSettings | null>(null);
+  useEffect(() => {
+    fetch('/api/marketplace/settings/public')
+      .then((r) => (r.ok ? r.json() : null))
+      .then((d) => d && setS(d))
+      .catch(() => undefined);
+  }, []);
+  return s;
+}
+
+const product = (id: string) => `${MARKETPLACE_URL}/product/${id}`;
+
+/* ------------------------------------------------------------------ Démarrer */
+
+function Introduction() {
+  return (
+    <>
+      <p>
+        Snapify est un CMS tunisien conçu pour être étendu sans toucher à son cœur. Deux types d’extensions existent, distribuées sous forme de
+        paquets signés et vendues ou offertes sur la <a href={MARKETPLACE_URL}>marketplace</a> :
+      </p>
+      <Table
+        head={['', 'Module', 'Thème']}
+        rows={[
+          ['Rôle', 'Ajoute une fonctionnalité : widget, page, API, administration', 'Fournit toute la présentation du site'],
+          ['Paquet', <C>.snapmod</C>, <C>.snaptheme</C>],
+          ['Manifeste', <C>snapify.module.json</C>, <C>snapify.theme.json</C>],
+          ['Code serveur', 'Oui (facultatif), avec permissions', 'Non'],
+          ['Actifs en même temps', 'Autant que nécessaire', 'Un seul'],
+        ]}
+      />
+      <H2>Comment ça marche</H2>
+      <p>
+        Le site hôte charge les données, gère la navigation, l’aperçu de l’éditeur, les cookies et la sécurité. Votre extension ne fait que ce
+        qu’elle déclare dans son manifeste :
+      </p>
+      <ul>
+        <li>
+          <strong>Côté navigateur</strong>, un module affiche des composants React dans des emplacements (<C>floating</C>,{' '}
+          <C>header-actions</C>), des pages complètes (<C>/agenda/*</C>) ou des widgets que l’éditeur insère dans une page.
+        </li>
+        <li>
+          <strong>Côté serveur</strong>, il reçoit un contexte (<C>ctx</C>) qui donne accès aux routes HTTP, à une base de données propre, aux
+          e-mails… uniquement pour les permissions demandées.
+        </li>
+        <li>
+          <strong>Dans l’administration</strong>, ses réglages deviennent un formulaire généré automatiquement, et il peut ajouter ses propres
+          pages au menu.
+        </li>
+      </ul>
+      <H2>Le SDK</H2>
+      <p>Les sources importent uniquement React, le SDK Snapify et des dépendances qui seront intégrées au bundle (ex. <C>lucide-react</C>).</p>
+      <Table
+        head={['Import', 'Contenu']}
+        rows={[
+          [<C>@snapify/sdk</C>, 'Manifeste, partie publique (definePublicModule) et serveur (defineServerModule), types'],
+          [<C>@snapify/sdk/admin</C>, 'Pages d’administration (defineAdminModule) et composants du back-office'],
+          [<C>@snapify/sdk/theme</C>, 'Contrat des thèmes : defineTheme, useSnapify, ModuleSlot'],
+          [<C>@snapify/sdk/content</C>, 'Types des blocs, pages, articles et de la configuration du site'],
+          [<C>@snapify/sdk/commerce</C>, 'Contrat e-commerce partagé (panier, client, adresses, statuts de commande)'],
+          [<C>@snapify/sdk/image</C>, 'Préparation d’images dans le navigateur avant envoi (prepareAvatar)'],
+          [<C>@snapify/sdk/icons</C>, 'Icônes disponibles dans l’éditeur de blocs'],
+        ]}
+      />
+      <Note title={`Version de l’API : ${API_VERSION}`}>
+        Déclarez la version minimale dont vous avez besoin dans <C>engines.snapify</C> (ex. <C>^1.2.0</C>). Un site plus ancien refusera
+        l’installation au lieu de planter.
+      </Note>
+      <Note tone="tip" title="Kit développeur">
+        Le SDK et l’outil <C>snapify</C> (création de projet, compilation, analyse marketplace) sont gratuits :{' '}
+        lancez <C>npm create snapify@latest</C> ou consultez la page <Link to="/docs/kit-developpeur">Kit développeur</Link>.
+      </Note>
+      <div className="flex flex-wrap gap-3 pt-2">
+        <NextLink to="/docs/kit-developpeur" label="Installer le kit" />
+        <NextLink to="/docs/demarrage-rapide" label="Créer votre premier module" />
+        <NextLink to="/docs/themes/creer-un-theme" label="Créer un thème" />
+      </div>
+    </>
+  );
+}
+
+type SdkFile = { name: string; kind: 'sdk' | 'starter'; size: number; sha256: string };
+type SdkRelease = { version: string; api: string; date: string; checksums: string; npm?: { sdk: string; create: string }; files: SdkFile[] };
+
+function useSdkReleases() {
+  const [state, setState] = useState<{ latest?: SdkRelease; releases: SdkRelease[]; failed: boolean }>({ releases: [], failed: false });
+  useEffect(() => {
+    fetch('/api/developers/sdk')
+      .then((r) => (r.ok ? r.json() : Promise.reject(new Error(String(r.status)))))
+      .then((d: { latest: string; releases: SdkRelease[] }) => setState({ latest: d.releases.find((r) => r.version === d.latest), releases: d.releases, failed: false }))
+      .catch(() => setState({ releases: [], failed: true }));
+  }, []);
+  return state;
+}
+
+const sdkUrl = (file: string) => `${SDK_DOWNLOAD_URL}/${file}`;
+const NPM_URL = 'https://www.npmjs.com/package';
+const kb = (n: number) => `${Math.round(n / 1024)} Ko`;
+const longDate = (iso: string) => new Date(iso).toLocaleDateString('fr-FR', { day: 'numeric', month: 'long', year: 'numeric' });
+
+function DownloadCard({ file, title, text }: { file?: SdkFile; title: string; text: string }) {
+  return (
+    <div className="flex flex-col rounded-xl border border-slate-200 p-5">
+      <div className="font-semibold text-navy">{title}</div>
+      <p className="mt-1 flex-1 text-sm text-slate-600">{text}</p>
+      {file ? (
+        <>
+          <a href={`/sdk/${file.name}`} download className="mt-4 inline-flex items-center justify-center rounded-lg bg-navy px-4 py-2 text-sm font-semibold text-white no-underline hover:bg-navy-2">
+            Télécharger {file.name.endsWith('.zip') ? '.zip' : '.tgz'} · {kb(file.size)}
+          </a>
+          <div className="mt-3 break-all font-mono text-[11px] leading-snug text-slate-500" title="Empreinte SHA-256">
+            SHA-256 {file.sha256}
+          </div>
+        </>
+      ) : (
+        <div className="mt-4 h-9 animate-pulse rounded-lg bg-slate-100" />
+      )}
+    </div>
+  );
+}
+
+function KitDownload() {
+  const { latest, releases, failed } = useSdkReleases();
+  const version = latest?.version ?? API_VERSION;
+  const sdk = latest?.files.find((f) => f.kind === 'sdk');
+  const starter = latest?.files.find((f) => f.kind === 'starter');
+  const tarball = sdkUrl(sdk?.name ?? `snapify-sdk-${version}.tgz`);
+  const npmName = latest?.npm?.sdk ?? 'snapify-sdk';
+
+  return (
+    <>
+      <p>
+        Le kit développeur réunit le SDK et ses déclarations TypeScript, l’outil en ligne de commande <C>snapify</C> et les modèles de projet.
+        Il est gratuit et publié par NOVALABS sur le registre npm sous le nom{' '}
+        <a href={`${NPM_URL}/${npmName}`} target="_blank" rel="noreferrer">
+          <C>{npmName}</C>
+        </a>
+        .
+      </p>
+      {failed ? (
+        <Note tone="warn" title="Liste des versions indisponible">
+          Réessayez dans un instant. Les commandes npm ci-dessous restent valables.
+        </Note>
+      ) : (
+        <p className="text-sm text-slate-500">
+          Version <strong className="text-navy">{latest?.version ?? '…'}</strong>
+          {latest ? <> · API {latest.api} · publiée le {longDate(latest.date)}</> : null}
+        </p>
+      )}
+      <Code lang="bash" title="nouveau projet">{`npm create snapify@latest`}</Code>
+      <p>
+        L’outil demande s’il s’agit d’un module ou d’un thème, le dossier et votre nom d’éditeur, puis prépare le projet : manifeste, sources
+        React et TypeScript, scripts npm.
+      </p>
+
+      <H2>Prérequis</H2>
+      <p>
+        Node.js <strong>20.19</strong> ou <strong>22.12</strong> et plus récent, npm 10 ou plus. React, Tailwind et Vite sont installés avec le
+        kit : rien d’autre à configurer.
+      </p>
+
+      <H2>Créer un projet</H2>
+      <Code lang="bash">{`
+npm create snapify@latest
+cd mon-module
+npm install
+npm run build
+`}</Code>
+      <p>
+        <C>npm run build</C> produit <C>dist/monagence.mon-module-1.0.0.snapmod</C> puis lance <strong>la même analyse que la marketplace</strong>{' '}
+        (manifeste, permissions, code, sécurité, présentation) : un paquet qui passe sur votre poste passe à l’envoi.
+      </p>
+      <p>Sans questions, pour un script ou une intégration continue :</p>
+      <Code lang="bash">{`
+# Module (remplacez « monagence » par votre nom d’éditeur)
+npm create snapify@latest mon-module -- --id monagence.mon-module
+
+# Thème
+npm create snapify@latest mon-theme -- --theme --id monagence.mon-theme
+`}</Code>
+
+      <H2>Ajouter le SDK à un projet existant</H2>
+      <p>
+        Le code des extensions importe le SDK sous le nom <C>@snapify/sdk</C>. Installez le paquet <C>{npmName}</C> sous ce nom :
+      </p>
+      <Code lang="bash">{`npm install --save-dev @snapify/sdk@npm:${npmName}@^${version}`}</Code>
+      <Note tone="warn" title="N’installez jamais « @snapify/sdk » seul">
+        Sur le registre npm, le nom <C>@snapify/sdk</C> n’appartient pas à NOVALABS. Le paquet officiel est <C>{npmName}</C> : utilisez toujours
+        l’alias ci-dessus, jamais <C>npm install @snapify/sdk</C> sans <C>npm:{npmName}</C>.
+      </Note>
+
+      <H2>Contenu du kit</H2>
+      <Table
+        head={['Élément', 'Rôle']}
+        rows={[
+          [<C>@snapify/sdk</C>, <>Imports des modules et des thèmes (<C>/admin</C>, <C>/theme</C>, <C>/content</C>…), avec leurs types</>],
+          [<C>snapify create</C>, 'Nouveau projet de module ou de thème : manifeste, sources, TypeScript, scripts npm'],
+          [<C>snapify build</C>, 'Compilation du paquet .snapmod / .snaptheme, puis analyse marketplace'],
+          [<C>snapify check</C>, 'Analyse d’un paquet existant, identique à celle de la marketplace'],
+          [<C>snapify verify</C>, 'Signature NOVALABS et licence d’un paquet reçu'],
+        ]}
+      />
+      <p>
+        Les paquets produits ne sont pas signés : ils s’installent sur un site Snapify en mode développeur. NOVALABS signe la version validée
+        lors de la <Link to="/docs/publier">revue marketplace</Link>.
+      </p>
+
+      <H2>Téléchargement direct</H2>
+      <p>
+        Pour un poste sans accès au registre npm, ou pour archiver une version, le kit et les projets de départ sont aussi disponibles ici.
+        L’archive du kit est identique à celle publiée sur npm.
+      </p>
+      <div className="grid gap-4 sm:grid-cols-2">
+        <DownloadCard file={sdk} title="Kit développeur" text="Paquet npm : SDK, types, outil snapify et modèles. À installer avec npm install plutôt qu’à décompresser." />
+        <DownloadCard file={starter} title="Projets de départ" text="Un module et un thème prêts à compiler, pour explorer le code avant de créer le vôtre." />
+      </div>
+      <Code lang="bash">{`
+# Installation depuis l’archive
+npm install --save-dev @snapify/sdk@${tarball}
+
+# Vérification des empreintes SHA-256
+curl -O ${tarball}
+curl -O ${sdkUrl(latest?.checksums ?? `SHA256SUMS-${version}.txt`)}
+sha256sum -c --ignore-missing ${latest?.checksums ?? `SHA256SUMS-${version}.txt`}
+
+# Windows (PowerShell)
+Get-FileHash ${sdk?.name ?? `snapify-sdk-${version}.tgz`} -Algorithm SHA256
+`}</Code>
+
+      <H2>Licence</H2>
+      <p>
+        Le kit est gratuit pour développer, tester et distribuer des extensions Snapify. Les extensions que vous créez vous appartiennent. Les
+        conditions complètes figurent dans le fichier <C>LICENSE.md</C> du paquet.
+      </p>
+
+      {releases.length ? (
+        <>
+          <H2>Versions</H2>
+          <Table
+            head={['Version', 'API', 'Date', 'npm', 'Fichiers']}
+            rows={releases.map((r) => [
+              <strong>{r.version}</strong>,
+              r.api,
+              longDate(r.date),
+              r.npm ? (
+                <a href={`${NPM_URL}/${r.npm.sdk}/v/${r.version}`} target="_blank" rel="noreferrer">
+                  {r.npm.sdk}@{r.version}
+                </a>
+              ) : (
+                '—'
+              ),
+              <span className="flex flex-wrap gap-x-3">
+                {r.files.map((f) => (
+                  <a key={f.name} href={`/sdk/${f.name}`} download>
+                    {f.name}
+                  </a>
+                ))}
+                <a href={`/sdk/${r.checksums}`}>{r.checksums}</a>
+              </span>,
+            ])}
+          />
+        </>
+      ) : null}
+
+      <div className="flex flex-wrap gap-3 pt-2">
+        <NextLink to="/docs/demarrage-rapide" label="Créer votre premier module" />
+        <NextLink to="/docs/reference/cli" label="Toutes les commandes" />
+      </div>
+    </>
+  );
+}
+
+function Quickstart() {
+  return (
+    <>
+      <p>
+        En quelques minutes, nous allons créer <strong>Bonjour</strong> : une bannière flottante dont le texte se règle dans l’administration et
+        qui compte les clics côté serveur.
+      </p>
+      <H2>1. Créer le projet</H2>
+      <p>
+        Avec le <Link to="/docs/kit-developpeur">kit développeur</Link> (Node.js 20.19+), une commande prépare le projet, ses dépendances et
+        TypeScript :
+      </p>
+      <Code lang="bash">{`
+npm create snapify@latest bonjour -- --id monagence.bonjour --name "Bonjour"
+cd bonjour
+npm install
+`}</Code>
+      <Code lang="text" title="structure">{`
+bonjour/
+├── package.json          # scripts build et typecheck, SDK en dépendance
+├── tsconfig.json
+├── snapify.module.json   # manifeste (obligatoire)
+├── README.md             # inclus dans le paquet
+└── src/
+    ├── public.tsx        # affiché sur le site
+    ├── server.ts         # code serveur (facultatif)
+    └── admin.tsx         # pages d’administration (facultatif)
+`}</Code>
+      <p>Le modèle contient déjà une bannière, un widget et une page de statistiques. Les étapes suivantes en expliquent l’essentiel.</p>
+      <H2>2. Écrire le manifeste</H2>
+      <Code lang="json" title="snapify.module.json">{`
+{
+  "id": "monagence.bonjour",
+  "name": "Bonjour",
+  "version": "1.0.0",
+  "description": "Bannière d’accueil flottante avec compteur de clics.",
+  "author": { "name": "Mon Agence", "email": "dev@monagence.tn", "url": "https://monagence.tn" },
+  "pricing": "free",
+  "category": "Marketing",
+  "icon": "sparkles",
+  "engines": { "snapify": "^1.3.0" },
+  "permissions": ["http:routes", "storage"],
+  "slots": ["floating"],
+  "entries": { "public": "src/public.tsx", "server": "src/server.ts" },
+  "settings": [
+    { "key": "message", "type": "text", "group": "Bannière", "label": "Message", "default": "Bienvenue !", "public": true, "maxLength": 80 },
+    { "key": "showOnPages", "type": "paths", "group": "Bannière", "label": "Pages", "default": [], "public": true }
+  ]
+}
+`}</Code>
+      <H2>3. La partie publique</H2>
+      <Code lang="tsx" title="src/public.tsx">{`
+import { definePublicModule, matchesPaths, type PublicModuleProps } from '@snapify/sdk';
+
+interface Settings { message: string; showOnPages: string[] }
+
+function Banner({ settings, path, isPreview, api }: PublicModuleProps<Settings>) {
+  if (isPreview || !matchesPaths(settings.showOnPages, path)) return null;
+  return (
+    <button
+      className="fixed bottom-5 left-5 rounded-full bg-px-primary px-5 py-3 font-semibold text-white shadow-lg"
+      onClick={() => api.post('/click')}
+    >
+      {settings.message}
+    </button>
+  );
+}
+
+export default definePublicModule<Settings>({ slots: { floating: Banner } });
+`}</Code>
+      <H2>4. La partie serveur</H2>
+      <Code lang="ts" title="src/server.ts">{`
+import { defineServerModule, type ServerContext } from '@snapify/sdk';
+
+export default defineServerModule({
+  activate(ctx: ServerContext) {
+    ctx.http.post('/click', async () => {
+      const clicks = ((await ctx.storage.get<number>('clicks')) ?? 0) + 1;
+      await ctx.storage.set('clicks', clicks);
+      return { clicks };
+    });
+
+    ctx.admin.status(async () => ({
+      stats: [{ label: 'Clics', value: (await ctx.storage.get<number>('clicks')) ?? 0 }],
+    }));
+  },
+});
+`}</Code>
+      <H2>5. Construire et tester</H2>
+      <Code lang="bash">{`
+# Compile dist/monagence.bonjour-1.0.0.snapmod puis l’analyse comme la marketplace
+npm run build
+
+# Vérifie les types TypeScript
+npm run typecheck
+`}</Code>
+      <Code lang="text" title="sortie (extrait)">{`
+✔ dist/monagence.bonjour-1.0.0.snapmod (0.9 s, non signé)
+
+• Analyse marketplace
+  Permissions
+    ✔ ctx.http (routes publiques) — permission http:routes déclarée
+    ✔ Permissions minimales — toutes les permissions déclarées sont utilisées
+  …
+✔ Analyse marketplace réussie : 23 contrôles, 0 erreur(s), 2 avertissement(s)
+`}</Code>
+      <p>
+        Pour voir le module en fonctionnement, importez <C>dist/monagence.bonjour-1.0.0.snapmod</C> sur un site Snapify de test en mode
+        développeur (<strong>Administration › Modules › Importer un module</strong>), activez-le, puis réglez le message dans sa page. La page{' '}
+        <Link to="/docs/tester">Tester une extension</Link> détaille la marche à suivre, y compris sans installation Snapify.
+      </p>
+      <H2>Et ensuite ?</H2>
+      <div className="flex flex-wrap gap-3">
+        <NextLink to="/docs/tester" label="Tester une extension" />
+        <NextLink to="/docs/modules/site-public" label="Pages et widgets" />
+        <NextLink to="/docs/modules/base-de-donnees" label="Base de données" />
+        <NextLink to="/docs/publier" label="Publier sur la marketplace" />
+      </div>
+    </>
+  );
+}
+
+/* ------------------------------------------------------------------ Modules */
+
+function Manifest() {
+  return (
+    <>
+      <p>
+        Le manifeste <C>snapify.module.json</C> décrit le module : identité, permissions, emplacements, réglages. L’administration l’affiche
+        avant installation et le site le contrôle à chaque démarrage.
+      </p>
+      <H2>Champs</H2>
+      <Table
+        head={['Champ', 'Règle']}
+        rows={[
+          [<C>id</C>, <>« éditeur.nom » en minuscules, chiffres et tirets, ex. <C>monagence.bonjour</C>. Ne change jamais. Les préfixes <C>novalabs.</C> et <C>snapify.</C> sont réservés.</>],
+          [<C>version</C>, <>SemVer <C>x.y.z</C>. Une version supérieure est proposée comme mise à jour.</>],
+          [<C>pricing</C>, <><C>free</C> (licence gratuite incluse) ou <C>paid</C> (clé de licence à saisir).</>],
+          [<C>engines.snapify</C>, <>Version d’API requise : <C>*</C>, <C>1.3.0</C>, <C>&gt;=1.2.0</C> ou <C>^1.3.0</C>.</>],
+          [<C>permissions</C>, <>Capacités serveur demandées, voir <Link to="/docs/reference/permissions">Permissions</Link>.</>],
+          [<C>slots</C>, <><C>floating</C> (fixé à l’écran) et/ou <C>header-actions</C> (icônes de l’en-tête, placées par le thème).</>],
+          [<C>entries</C>, <><C>public</C>, <C>server</C>, <C>admin</C> : chemins vers les sources.</>],
+          [<C>settings</C>, <>Réglages, voir <Link to="/docs/modules/reglages">Réglages</Link>.</>],
+          [<C>routes</C>, <>Adresses gérées par le module : <C>/panier/</C> (exacte) ou <C>/boutique/*</C> (avec sous-pages).</>],
+          [<C>widgets</C>, 'Widgets insérables dans une page avec le bloc « Module » de l’éditeur.'],
+          [<C>adminPages</C>, 'Pages ajoutées au menu de l’administration.'],
+          [<C>requires</C>, <>Modules indispensables et version : <C>{'{ "novalabs.shop": "^1.0.0" }'}</C>.</>],
+          [<C>uses</C>, 'Modules facultatifs dont le module utilise les services s’ils sont actifs.'],
+          [<><C>category</C>, <C>icon</C>, <C>screenshot</C></>, 'Présentation dans l’administration et sur la marketplace.'],
+        ]}
+      />
+      <H2>Icônes</H2>
+      <p>
+        <C>icon</C> accepte : <C>bot</C>, <C>calendar</C>, <C>chart-bar</C>, <C>credit-card</C>, <C>database</C>, <C>folder</C>,{' '}
+        <C>globe</C>, <C>heart</C>, <C>mail</C>, <C>message-circle</C>, <C>messages-square</C>, <C>package</C>, <C>phone</C>,{' '}
+        <C>receipt</C>, <C>search</C>, <C>shopping-bag</C>, <C>shopping-cart</C>, <C>sparkles</C>, <C>store</C>, <C>tag</C>,{' '}
+        <C>ticket</C>, <C>truck</C>, <C>user</C>, <C>users</C>. Une autre valeur affiche une icône générique.
+      </p>
+      <H2>Capture d’écran</H2>
+      <p>
+        <C>"screenshot": "screenshot.jpg"</C> intègre une image JPEG, PNG ou WebP (2 Mo maximum) au paquet. Elle sert de couverture sur la
+        marketplace et dans l’administration. Format conseillé : 1280 × 720 pour un module, 4:3 pour un thème.
+      </p>
+      <H2>Exemple complet</H2>
+      <Code lang="json" title="snapify.module.json du Calendrier (extrait)">{`
+{
+  "id": "novalabs.calendar",
+  "name": "Calendrier",
+  "version": "1.0.1",
+  "pricing": "free",
+  "icon": "calendar",
+  "screenshot": "screenshot.jpg",
+  "engines": { "snapify": "^1.2.0" },
+  "permissions": ["http:routes", "admin:routes", "database"],
+  "slots": [],
+  "routes": ["/agenda/*", "/calendrier/*"],
+  "entries": { "public": "src/public/index.tsx", "server": "src/server.ts", "admin": "src/admin/index.tsx" },
+  "adminPages": [{ "id": "events", "label": "Événements", "icon": "calendar" }],
+  "widgets": [
+    {
+      "id": "upcoming",
+      "label": "Prochains événements",
+      "fields": [{ "key": "limit", "type": "number", "label": "Nombre d’événements", "default": 5, "min": 1, "max": 20 }]
+    }
+  ]
+}
+`}</Code>
+    </>
+  );
+}
+
+function SettingsDoc() {
+  return (
+    <>
+      <p>
+        Chaque entrée de <C>settings</C> devient un champ de la page du module dans l’administration. Les valeurs sont validées côté serveur
+        avant d’être enregistrées, selon le type déclaré.
+      </p>
+      <H2>Types de champs</H2>
+      <Table
+        head={['type', 'Valeur', 'Options utiles']}
+        rows={[
+          [<C>boolean</C>, <><C>true</C> / <C>false</C></>, '—'],
+          [<><C>text</C>, <C>phone</C></>, 'chaîne', <><C>maxLength</C>, <C>placeholder</C></>],
+          [<C>textarea</C>, 'chaîne', <><C>rows</C>, <C>maxLength</C>, <C>monospace</C></>],
+          [<C>number</C>, 'nombre', <><C>min</C>, <C>max</C>, <C>step</C>, <C>slider</C></>],
+          [<C>select</C>, <>une des <C>options[].value</C></>, <C>options</C>],
+          [<C>paths</C>, <>liste d’adresses (<C>/contact/</C>, <C>/blog/*</C>)</>, 'vide = toutes les pages'],
+        ]}
+      />
+      <p>
+        Options communes : <C>key</C> (lettres, chiffres, <C>_</C>), <C>label</C>, <C>help</C>, <C>group</C> (les champs consécutifs du même
+        groupe forment une section), <C>default</C>, <C>required</C>.
+      </p>
+      <H2>Réglages publics et privés</H2>
+      <p>
+        Par défaut, un réglage reste <strong>côté serveur</strong>. Seuls les champs marqués <C>"public": true</C> sont transmis au
+        navigateur des visiteurs.
+      </p>
+      <Code lang="json">{`
+"settings": [
+  { "key": "title", "type": "text", "label": "Titre", "default": "Assistant", "public": true, "maxLength": 60 },
+  { "key": "systemPrompt", "type": "textarea", "label": "Instructions", "default": "", "rows": 6, "monospace": true },
+  { "key": "model", "type": "select", "label": "Modèle", "default": "flash",
+    "options": [{ "value": "flash", "label": "Rapide" }, { "value": "pro", "label": "Précis" }] }
+]
+`}</Code>
+      <Note tone="warn">
+        Ne marquez jamais <C>public</C> un prompt, un quota, un identifiant ou une clé : tout ce qui est public est lisible dans le code de la
+        page. Les clés d’API se lisent avec <C>ctx.env()</C>, pas dans les réglages.
+      </Note>
+      <H2>Lire les réglages</H2>
+      <ul>
+        <li>
+          Navigateur : <C>props.settings</C> (réglages publics uniquement).
+        </li>
+        <li>
+          Serveur : <C>ctx.settings()</C> renvoie tous les réglages, à jour à chaque appel.
+        </li>
+        <li>
+          Administration : <C>props.settings</C> d’une page d’administration, et <C>canConfigure</C> pour savoir si l’utilisateur peut les
+          modifier.
+        </li>
+      </ul>
+    </>
+  );
+}
+
+function PublicSide() {
+  return (
+    <>
+      <p>
+        L’entrée <C>public</C> exporte un <C>definePublicModule()</C> qui peut fournir trois types de composants : des emplacements, une page
+        et des widgets.
+      </p>
+      <H2>Props communes</H2>
+      <Table
+        head={['Prop', 'Description']}
+        rows={[
+          [<C>settings</C>, 'Réglages marqués public.'],
+          [<C>site</C>, 'Nom, raison sociale, téléphone, e-mail, adresse du site.'],
+          [<C>path</C>, 'Adresse de la page affichée.'],
+          [<C>isPreview</C>, <><C>true</C> dans l’aperçu de l’éditeur : les widgets interactifs peuvent se masquer.</>],
+          [<C>navigate(path)</C>, 'Navigation interne sans rechargement.'],
+          [<><C>api.get</C>, <C>api.post</C></>, <>Appels vers vos routes serveur <C>/api/modules/&lt;id&gt;/…</C></>],
+          [<C>module</C>, <>Identifiant et version du module.</>],
+        ]}
+      />
+      <H2>Emplacements</H2>
+      <p>
+        <C>floating</C> affiche un élément fixé à l’écran (bulle de chat, bouton WhatsApp). <C>header-actions</C> place des icônes dans
+        l’en-tête, à l’endroit choisi par le thème (panier, compte client).
+      </p>
+      <Code lang="tsx">{`
+export default definePublicModule<Settings>({
+  slots: { floating: ChatBubble, 'header-actions': CartIcon },
+});
+`}</Code>
+      <H2>Pages</H2>
+      <p>
+        Déclarez les adresses dans <C>routes</C> du manifeste ; le composant <C>page</C> est affiché entre l’en-tête et le pied de page du
+        thème. Il reçoit en plus <C>search</C> (paramètres de l’adresse) et <C>setMeta()</C> pour le titre et la description SEO.
+      </p>
+      <Code lang="tsx">{`
+import { definePublicModule, type PublicPageProps } from '@snapify/sdk';
+
+function AgendaPage({ path, search, setMeta, api }: PublicPageProps<Settings>) {
+  setMeta({ title: 'Agenda', description: 'Nos prochains événements' });
+  const slug = path.replace(/^\\/agenda\\/?/, '').replace(/\\/$/, '');
+  return slug ? <EventDetail slug={slug} api={api} /> : <EventList query={search} api={api} />;
+}
+
+export default definePublicModule<Settings>({ page: AgendaPage });
+`}</Code>
+      <H2>Widgets</H2>
+      <p>
+        Un widget est inséré dans n’importe quelle page avec le bloc <strong>Module</strong> de l’éditeur. Ses options (<C>fields</C> du
+        manifeste) sont saisies dans l’éditeur et reçues dans <C>options</C>, complétées par les valeurs par défaut.
+      </p>
+      <Code lang="tsx">{`
+import { definePublicModule, type WidgetProps } from '@snapify/sdk';
+
+function Upcoming({ options, api, navigate }: WidgetProps<Settings, { title: string; limit: number }>) {
+  // …charger /events?limit=options.limit puis afficher la liste
+  return <section><h2>{options.title}</h2>…</section>;
+}
+
+export default definePublicModule<Settings>({ widgets: { upcoming: Upcoming } });
+`}</Code>
+      <H2>Styles</H2>
+      <p>
+        Tailwind est compilé avec le module : seules les classes utilisées sont incluses. Les couleurs du site sont disponibles via les classes{' '}
+        <C>px-*</C> (<C>bg-px-primary</C>, <C>text-px-navy</C>…), ce qui aligne le module sur l’identité visuelle choisie par le client.
+      </p>
+      <ul>
+        <li>
+          La feuille de style est limitée au conteneur du module (<C>[data-snapify-scope="&lt;id&gt;"]</C>) : elle ne peut pas modifier le
+          thème ni les autres modules.
+        </li>
+        <li>React est fourni par le site ; il n’est jamais embarqué dans votre bundle.</li>
+        <li>Une erreur dans un module est isolée : elle n’affecte ni la page ni les autres modules.</li>
+      </ul>
+      <H2>Utilitaires</H2>
+      <ul>
+        <li>
+          <C>matchesPaths(patterns, path)</C> : liste vide = toutes les pages ; <C>/blog/*</C> inclut les sous-pages.
+        </li>
+        <li>
+          <C>createModuleApi(id)</C> : client des routes publiques d’un autre module actif.
+        </li>
+        <li>
+          <C>isModuleActive(id)</C> : savoir si un module est actif sur le site.
+        </li>
+      </ul>
+    </>
+  );
+}
+
+function ServerSide() {
+  return (
+    <>
+      <p>
+        L’entrée <C>server</C> exporte un <C>defineServerModule()</C>. Sa fonction <C>activate(ctx)</C> est appelée à l’activation ; la
+        fonction qu’elle renvoie éventuellement est appelée à la désactivation.
+      </p>
+      <Code lang="ts">{`
+import { defineServerModule, type ServerContext } from '@snapify/sdk';
+
+interface Settings { greeting: string }
+
+export default defineServerModule<Settings>({
+  activate(ctx: ServerContext<Settings>) {
+    ctx.http.post('/hello', async (req) => {
+      const { name } = (req.body ?? {}) as { name?: string };
+      if (typeof name !== 'string' || !name.trim()) throw ctx.error(400, 'Nom manquant');
+      return { message: ctx.settings().greeting + ' ' + name.slice(0, 50) };
+    });
+
+    const timer = setInterval(() => ctx.log.info('toujours actif'), 3_600_000);
+    return () => clearInterval(timer);
+  },
+});
+`}</Code>
+      <H2>Le contexte ctx</H2>
+      <p>Chaque capacité est liée à une permission du manifeste ; sans elle, l’appel lève une erreur.</p>
+      <Table
+        head={['API', 'Permission', 'Rôle']}
+        rows={[
+          [<><C>ctx.http.get/post(route, handler)</C></>, <C>http:routes</C>, <>Routes publiques sous <C>/api/modules/&lt;id&gt;/…</C>, segments <C>:nom</C> acceptés.</>],
+          [<C>ctx.http.reply(body, opts)</C>, <C>http:cookies</C>, <>Choisir le statut et déposer des cookies <C>sm_*</C>.</>],
+          [<C>ctx.db.collection(nom)</C>, <C>database</C>, <>Collections d’enregistrements, voir <Link to="/docs/modules/base-de-donnees">Base de données</Link>.</>],
+          [<C>ctx.storage.get/set/delete</C>, <C>storage</C>, 'Valeurs JSON clé/valeur (64 Ko max.).'],
+          [<C>ctx.files.saveImage/delete</C>, <C>files</C>, <>Images publiques sous <C>/uploads/modules/&lt;id&gt;/</C> (2 Mo max.).</>],
+          [<C>ctx.mail.send/render</C>, <C>mail:send</C>, 'E-mails via le SMTP du site, gabarit aux couleurs du site.'],
+          [<C>ctx.site()</C>, <C>site:read</C>, 'Coordonnées, couleurs et URL publique du site.'],
+          [<C>ctx.env(NOM)</C>, <C>env:NOM</C>, 'Une variable d’environnement précise (clé d’API…).'],
+          [<C>ctx.fetch(url, init)</C>, <C>net:hôte</C>, 'Requête HTTPS vers cet hôte uniquement, 30 s max.'],
+          [<C>ctx.admin.get/post/put/delete</C>, <C>admin:routes</C>, <>Routes réservées à l’administration (<C>/api/admin/modules/&lt;id&gt;/api/…</C>).</>],
+          [<><C>ctx.settings()</C>, <C>ctx.log</C>, <C>ctx.error()</C>, <C>ctx.lock()</C>, <C>ctx.admin.status()</C>, <C>ctx.provide/use</C></>, '—', 'Toujours disponibles.'],
+        ]}
+      />
+      <H2>Requêtes et réponses</H2>
+      <p>
+        Le handler reçoit <C>req</C> : <C>method</C>, <C>path</C>, <C>params</C>, <C>query</C>, <C>body</C>, <C>ip</C>, <C>userAgent</C>,{' '}
+        <C>cookies</C> (avec <C>http:cookies</C>) et <C>admin</C> (utilisateur connecté, routes d’administration). La valeur renvoyée est
+        sérialisée en JSON.
+      </p>
+      <Code lang="ts">{`
+ctx.http.post('/login', async (req) => {
+  const session = await createSession(req.body);
+  return ctx.http.reply({ ok: true }, {
+    status: 201,
+    cookies: [{ name: 'sm_session', value: session.token, maxAgeSec: 30 * 24 * 3600 }],
+  });
+});
+`}</Code>
+      <ul>
+        <li>
+          <C>throw ctx.error(422, 'Message')</C> renvoie ce statut et ce message au visiteur. Toute autre exception renvoie une erreur 500
+          générique et est journalisée côté serveur.
+        </li>
+        <li>Les routes publiques sont limitées à 120 requêtes par minute et par adresse IP ; un handler est interrompu après 60 s.</li>
+        <li>
+          Les cookies sont toujours <C>HttpOnly</C>, <C>SameSite=Lax</C>, <C>Path=/</C> et <C>Secure</C> en HTTPS ; leur nom doit commencer
+          par <C>sm_</C>.
+        </li>
+      </ul>
+      <H2>E-mails</H2>
+      <Code lang="ts">{`
+const { html, text } = ctx.mail.render({
+  title: 'Commande confirmée',
+  intro: 'Merci pour votre commande n° 1042.',
+  lines: ['Livraison sous 48 h'],
+  button: { label: 'Suivre ma commande', url: ctx.site().publicUrl + '/compte/' },
+});
+const { sent, reason } = await ctx.mail.send({ to: client.email, subject: 'Commande confirmée', html, text });
+`}</Code>
+      <p>
+        <C>send()</C> n’échoue jamais : vérifiez <C>sent</C> (par exemple si le SMTP du site n’est pas configuré).
+      </p>
+      <H2>Sections critiques</H2>
+      <p>
+        <C>ctx.lock(clé, fn)</C> exécute <C>fn</C> sans concurrence pour une même clé : décrément de stock, numérotation de commandes…
+      </p>
+      <Code lang="ts">{`
+const number = await ctx.lock('order-number', async () => {
+  const next = ((await ctx.storage.get<number>('lastOrder')) ?? 1000) + 1;
+  await ctx.storage.set('lastOrder', next);
+  return next;
+});
+`}</Code>
+    </>
+  );
+}
+
+function Database() {
+  return (
+    <>
+      <p>
+        Avec la permission <C>database</C>, un module dispose de collections d’enregistrements JSON qui lui sont propres. Elles sont supprimées
+        à la désinstallation.
+      </p>
+      <Code lang="ts">{`
+interface CalEvent { title: string; date: string; status: 'draft' | 'published' }
+
+const events = ctx.db.collection<CalEvent>('events');
+
+const created = await events.insert({ title: 'Atelier', date: '2026-10-17', status: 'published' });
+await events.update(created.id, { title: 'Atelier découverte' });
+
+const { items, total } = await events.find({
+  where: { status: 'published' },
+  filters: [{ field: 'date', op: 'gte', value: '2026-10-01' }],
+  search: { fields: ['title'], text: 'atelier' },
+  orderBy: [{ field: 'date', dir: 'asc' }],
+  limit: 20,
+  offset: 0,
+});
+`}</Code>
+      <H2>Méthodes</H2>
+      <Table
+        head={['Méthode', 'Rôle']}
+        rows={[
+          [<C>get(id)</C>, <>Un enregistrement ou <C>null</C>.</>],
+          [<C>getMany(ids)</C>, 'Plusieurs enregistrements.'],
+          [<C>find(query)</C>, <><C>{'{ items, total }'}</C> selon les filtres.</>],
+          [<C>findOne(where)</C>, 'Premier enregistrement correspondant.'],
+          [<C>count(query)</C>, 'Nombre d’enregistrements.'],
+          [<C>insert(data, {'{ id }'})</C>, 'Crée un enregistrement (identifiant aléatoire si absent).'],
+          [<C>update(id, patch)</C>, <>Fusion superficielle ; <C>null</C> si absent.</>],
+          [<C>delete(id)</C>, <><C>true</C> si supprimé.</>],
+        ]}
+      />
+      <p>
+        Chaque enregistrement reçoit <C>id</C>, <C>createdAt</C> et <C>updatedAt</C>. Taille maximale : 256 Ko par enregistrement.
+      </p>
+      <H2>Requêtes</H2>
+      <ul>
+        <li>
+          <C>where</C> : égalités simples sur des champs de premier niveau (un tableau doit contenir la valeur donnée).
+        </li>
+        <li>
+          <C>filters</C> : opérateurs <C>eq</C>, <C>ne</C>, <C>gt</C>, <C>gte</C>, <C>lt</C>, <C>lte</C>, <C>in</C>, <C>contains</C>,{' '}
+          <C>exists</C>.
+        </li>
+        <li>
+          <C>search</C> : recherche insensible à la casse et aux accents dans des champs texte.
+        </li>
+        <li>
+          <C>orderBy</C> : plusieurs critères, <C>numeric: true</C> pour trier des nombres.
+        </li>
+        <li>
+          <C>limit</C> : 100 par défaut, 500 au maximum.
+        </li>
+      </ul>
+      <Note tone="tip">Pour un simple compteur ou un paramètre interne, préférez <C>ctx.storage</C> (permission <C>storage</C>).</Note>
+    </>
+  );
+}
+
+function Admin() {
+  return (
+    <>
+      <p>
+        Un module peut ajouter des pages au menu de l’administration (liste d’événements, commandes, clients…). Elles utilisent les composants
+        du back-office : elles ont exactement la même apparence que le reste de l’administration.
+      </p>
+      <H2>Déclarer les pages</H2>
+      <Code lang="json" title="snapify.module.json">{`
+"permissions": ["admin:routes", "database"],
+"entries": { "public": "src/public/index.tsx", "server": "src/server.ts", "admin": "src/admin/index.tsx" },
+"adminPages": [{ "id": "events", "label": "Événements", "icon": "calendar" }]
+`}</Code>
+      <Code lang="tsx" title="src/admin/index.tsx">{`
+import { defineAdminModule } from '@snapify/sdk/admin';
+import { EventsPage } from './EventsPage';
+
+export default defineAdminModule({ pages: { events: EventsPage } });
+`}</Code>
+      <p>
+        La page est servie à <C>/administrator/m/&lt;id&gt;/&lt;page&gt;</C>. Elle reçoit <C>api</C> (routes d’administration),{' '}
+        <C>subpath</C> et <C>navigate()</C> pour ses sous-pages, <C>settings</C>, <C>user</C> et <C>canConfigure</C>.
+      </p>
+      <H2>Composants du back-office</H2>
+      <Code lang="tsx" title="src/admin/EventsPage.tsx">{`
+import { CalendarDays } from 'lucide-react';
+import { Button, Card, EmptyState, PageHeader, Table, toast, useAsync, type AdminPageProps } from '@snapify/sdk/admin';
+
+export function EventsPage({ api }: AdminPageProps) {
+  const { data, reload } = useAsync(() => api.get<{ items: Event[] }>('/events'), []);
+  const remove = async (id: string) => {
+    await api.delete('/events/' + id);
+    toast.success('Événement supprimé');
+    reload();
+  };
+  return (
+    <>
+      <PageHeader title="Événements" actions={<Button>Nouvel événement</Button>} />
+      <Card>
+        {data?.items.length ? <Table>…</Table> : <EmptyState icon={CalendarDays} title="Aucun événement" />}
+      </Card>
+    </>
+  );
+}
+`}</Code>
+      <p>Composants disponibles :</p>
+      <p className="text-[14px] leading-7">
+        {[
+          'Alert', 'Badge', 'Button', 'Card', 'Drawer', 'Dropdown', 'EmptyState', 'ErrorState', 'Field', 'ImageField', 'Input', 'MediaPicker',
+          'Modal', 'PageHeader', 'PageSkeleton', 'Pagination', 'RichTextEditor', 'Section', 'Segmented', 'Select', 'Skeleton', 'Spinner',
+          'StatCard', 'Switch', 'Table', 'Tabs', 'TagInput', 'Td', 'Textarea', 'Th',
+        ].map((n, i) => (
+          <span key={n}>
+            {i > 0 && ' '}
+            <C>{n}</C>
+          </span>
+        ))}
+      </p>
+      <p>
+        Outils : <C>toast</C>, <C>useAsync</C>, <C>useConfirm</C>, <C>useDebounced</C>, <C>usePagination</C>, <C>usePaging</C>,{' '}
+        <C>errorMessage</C>, <C>fmtDate</C>, <C>fmtDateTime</C>, <C>fmtNumber</C>, <C>timeAgo</C>, <C>slugify</C>, <C>downloadCsv</C>, <C>cx</C>.
+      </p>
+      <Note tone="warn" title="Deux pièges fréquents">
+        <C>Input</C> et <C>Textarea</C> sont des champs natifs : leur <C>onChange</C> reçoit un événement (lisez{' '}
+        <C>e.target.value</C>), alors que <C>Select</C>, <C>Switch</C>, <C>Segmented</C> et <C>TagInput</C> reçoivent directement la valeur.
+        Et une <C>Modal</C> ne s’affiche qu’avec <C>open</C>.
+      </Note>
+      <H2>Routes d’administration</H2>
+      <Code lang="ts">{`
+ctx.admin.get('/events', async () => ({ items: (await events.find({ limit: 500 })).items }));
+ctx.admin.delete('/events/:id', async (req) => ({ ok: await events.delete(req.params.id) }));
+`}</Code>
+      <p>
+        Elles ne sont accessibles qu’aux utilisateurs autorisés à gérer les données des modules ; <C>req.admin</C> contient l’utilisateur
+        connecté.
+      </p>
+      <H2>Statistiques et alertes</H2>
+      <p>
+        <C>ctx.admin.status()</C> alimente les indicateurs affichés en haut de la page du module, sans permission particulière :
+      </p>
+      <Code lang="ts">{`
+ctx.admin.status(async () => {
+  const drafts = await events.count({ where: { status: 'draft' } });
+  return {
+    stats: [{ label: 'Événements', value: await events.count() }],
+    alerts: drafts ? [{ tone: 'info', text: drafts + ' brouillon(s) en attente de publication.' }] : [],
+  };
+});
+`}</Code>
+    </>
+  );
+}
+
+function Dependencies() {
+  return (
+    <>
+      <p>
+        Les modules peuvent coopérer : le Panier s’appuie sur la Boutique, la Commande sur le Panier, l’Espace client utilise la Commande s’il
+        est installé.
+      </p>
+      <Table
+        head={['Champ', 'Effet']}
+        rows={[
+          [<C>requires</C>, 'Modules indispensables avec leur version. Si l’un manque ou n’est pas compatible, le module reste bloqué et l’administration indique pourquoi.'],
+          [<C>uses</C>, 'Modules facultatifs : leurs services sont utilisés s’ils sont actifs.'],
+        ]}
+      />
+      <Code lang="json">{`
+"requires": { "novalabs.shop": "^1.0.0", "novalabs.cart": "^1.0.0" },
+"uses": ["novalabs.customers"]
+`}</Code>
+      <H2>Publier et utiliser des services</H2>
+      <Code lang="ts" title="module fournisseur">{`
+ctx.provide({
+  async getProduct(id: string) { return products.get(id); },
+  async reserveStock(id: string, qty: number) { /* … */ },
+});
+`}</Code>
+      <Code lang="ts" title="module consommateur">{`
+interface ShopServices { getProduct(id: string): Promise<Product | null> }
+
+const shop = ctx.use<ShopServices>('novalabs.shop');
+const customers = ctx.use<CustomerServices>('novalabs.customers'); // null si inactif
+`}</Code>
+      <p>
+        Côté navigateur, <C>createModuleApi('novalabs.shop')</C> appelle les routes publiques d’un autre module, et <C>@snapify/sdk/commerce</C>{' '}
+        partage l’état du panier et du client entre les modules e-commerce.
+      </p>
+    </>
+  );
+}
+
+/* ------------------------------------------------------------------ Thèmes */
+
+function ThemeCreate() {
+  return (
+    <>
+      <p>
+        Un thème fournit toute la présentation : en-tête, pied de page, rendu des blocs, mise en page des pages et des articles, page 404. Le
+        contenu (pages, menus, articles, identité visuelle) ne dépend pas du thème : changer de thème ne modifie aucune donnée.
+      </p>
+      <H2>Créer le projet</H2>
+      <Code lang="bash">{`
+npm create snapify@latest mon-theme -- --theme --id monagence.mon-theme
+cd mon-theme
+npm install
+npm run build
+`}</Code>
+      <p>
+        Le modèle est un thème complet et fonctionnel : en-tête avec menu mobile, pied de page, cinq blocs, page article, page 404 et trois
+        options. Il passe l’analyse marketplace dès sa création : remplacez-le progressivement par votre design.
+      </p>
+      <Code lang="text" title="structure">{`
+mon-theme/
+├── package.json          # scripts build et typecheck, SDK en dépendance
+├── tsconfig.json
+├── snapify.theme.json    # manifeste (mêmes champs qu’un module, sans permissions ni slots)
+├── README.md             # inclus dans le paquet
+└── src/
+    ├── index.tsx         # export default defineTheme({...})
+    ├── Header.tsx, Footer.tsx
+    ├── blocks.tsx        # rendu des blocs de l’éditeur
+    ├── Views.tsx         # article, page 404
+    ├── site.tsx          # options, menus, liens, textes à variables
+    └── styles.css        # importé depuis l’entrée ; Tailwind est disponible
+`}</Code>
+      <p>
+        Ajoutez une capture d’écran (<C>screenshot.jpg</C>, format 4:3, JPEG, PNG ou WebP, 2 Mo max.) à la racine et déclarez-la dans le
+        manifeste avec <C>"screenshot": "screenshot.jpg"</C>.
+      </p>
+      <H2>Règles</H2>
+      <ul>
+        <li>
+          <C>entries.public</C> est obligatoire ; <C>entries.server</C>, <C>permissions</C> et <C>slots</C> sont interdits.
+        </li>
+        <li>
+          Les <C>settings</C> deviennent les <strong>options du thème</strong>, modifiables dans <em>Apparence › Personnaliser</em> avec
+          aperçu en direct. Elles sont toutes transmises au navigateur.
+        </li>
+      </ul>
+      <H2>Le contrat defineTheme</H2>
+      <Code lang="tsx" title="src/index.tsx">{`
+import { defineTheme, ModuleSlot, useSnapify, type BlockProps } from '@snapify/sdk/theme';
+import './styles.css';
+
+function Header({ path, navigate }) {
+  const { site, settings } = useSnapify<{ sticky: boolean }>();
+  return (
+    <header className={settings.sticky ? 'sticky top-0' : ''}>
+      <a onClick={() => navigate('/')}>{site.branding.siteName}</a>
+      {/* menus : site.menus … */}
+      <ModuleSlot name="header-actions" />
+    </header>
+  );
+}
+
+export default defineTheme({
+  Header,
+  Footer: ({ navigate, openCookies }) => <footer>…</footer>,
+  Layout: ({ children }) => <div className="theme-root">{children}</div>,   // facultatif
+  Page: ({ page, children }) => <main>{children}</main>,                   // facultatif
+  Post: ({ post, children }) => <article>{children}</article>,             // facultatif
+  NotFound: ({ navigate }) => <p>Page introuvable</p>,                     // facultatif
+  blocks: {
+    hero: ({ d, style }: BlockProps<'hero'>) => <section>{d.title}</section>,
+    // un bloc sans rendu n’est pas affiché ; l’aperçu de l’éditeur le signale
+  },
+});
+`}</Code>
+      <H2>useSnapify()</H2>
+      <Table
+        head={['Valeur', 'Contenu']}
+        rows={[
+          [<C>site</C>, 'Configuration publique : menus, identité visuelle, réglages généraux.'],
+          [<C>info</C>, 'Coordonnées du site.'],
+          [<C>tokens</C>, <>Valeurs des variables <C>{'{{telephone}}'}</C>, <C>{'{{email}}'}</C>… (voir <C>applyTokens()</C>).</>],
+          [<C>settings</C>, 'Options du thème.'],
+          [<><C>path</C>, <C>navigate</C>, <C>openCookies</C></>, 'Adresse, navigation, bannière cookies.'],
+          [<C>isPreview</C>, 'Aperçu de l’administration : aucune action réelle (formulaires, liens externes).'],
+        ]}
+      />
+      <H2>Modules dans le thème</H2>
+      <p>
+        Placez <C>&lt;ModuleSlot name="header-actions" /&gt;</C> dans l’en-tête pour afficher les icônes des modules (panier, compte).{' '}
+        <C>hasModuleSlot()</C> et <C>isModuleActive()</C> permettent d’adapter la mise en page.
+      </p>
+      <H2>Fonctionnement</H2>
+      <ul>
+        <li>Un seul thème est actif. Un thème installé n’est pas activé automatiquement s’il en existe déjà un actif.</li>
+        <li>La feuille de style et le script du thème actif sont inclus dans le HTML : pas de flash sans style.</li>
+        <li>Un thème inactif peut être prévisualisé et réglé avant activation.</li>
+        <li>Chaque partie est isolée : une erreur dans un bloc n’affecte pas le reste de la page.</li>
+        <li>
+          Si le thème actif est bloqué (signature, licence…), le site s’affiche avec un rendu minimal en attendant une réparation.
+        </li>
+      </ul>
+      <Note tone="tip" title="Partir d’un exemple">
+        Les thèmes officiels <a href={product('novalabs.sidibou')}>SidiBou</a>, <a href={product('novalabs.mahdia')}>Mahdia</a> et{' '}
+        <a href={product('novalabs.dogga')}>Dogga</a> implémentent tout le contrat, y compris l’e-commerce.
+      </Note>
+    </>
+  );
+}
+
+const BLOCKS: [string, string][] = [
+  ['hero', 'Bandeau principal'],
+  ['pageHeader', 'En-tête de page'],
+  ['richText', 'Texte riche'],
+  ['textMedia', 'Texte et image'],
+  ['image', 'Image'],
+  ['video', 'Vidéo'],
+  ['slides', 'Diaporama'],
+  ['cards', 'Cartes'],
+  ['showcase', 'Vitrine'],
+  ['steps', 'Étapes'],
+  ['stats', 'Chiffres clés'],
+  ['cta', 'Appel à l’action'],
+  ['panels', 'Panneaux'],
+  ['gallery', 'Galerie'],
+  ['checklist', 'Liste à cocher'],
+  ['faq', 'FAQ'],
+  ['marquee', 'Défilement'],
+  ['projects', 'Réalisations'],
+  ['table', 'Tableau'],
+  ['simulator', 'Simulateur'],
+  ['contactForm', 'Formulaire de contact'],
+  ['details', 'Détails'],
+  ['testimonials', 'Témoignages'],
+  ['spacer', 'Espacement'],
+  ['html', 'HTML personnalisé'],
+  ['module', 'Widget d’un module'],
+];
+
+function ThemeBlocks() {
+  return (
+    <>
+      <p>
+        Les pages sont composées de blocs dans l’éditeur. Le thème fournit le rendu de chaque type dans <C>blocks</C> ; chaque composant
+        reçoit <C>d</C> (données du bloc, complétées par les valeurs par défaut) et <C>style</C> (espacements, fond, alignement).
+      </p>
+      <Table head={['Type', 'Bloc']} rows={BLOCKS.map(([k, label]) => [<C>{k}</C>, label])} />
+      <H2>Typage</H2>
+      <Code lang="tsx">{`
+import type { BlockProps } from '@snapify/sdk/theme';
+import { applyTokens } from '@snapify/sdk/content';
+
+export function Cta({ d, style }: BlockProps<'cta'>) {
+  const { tokens } = useSnapify();
+  return (
+    <section data-bg={style.background}>
+      <h2>{applyTokens(d.title, tokens)}</h2>
+    </section>
+  );
+}
+`}</Code>
+      <Note>
+        Le bloc <C>module</C> affiche le widget d’un module : le site hôte s’occupe du rendu. Un thème peut se contenter de l’envelopper dans
+        sa mise en page.
+      </Note>
+    </>
+  );
+}
+
+/* ------------------------------------------------------------------ Distribution */
+
+function Testing() {
+  return (
+    <>
+      <p>
+        Une extension se teste à trois niveaux : sur votre poste avec le kit, sur un site Snapify de test, puis par NOVALABS pendant la revue
+        marketplace.
+      </p>
+
+      <H2>1. Sur votre poste</H2>
+      <Code lang="bash">{`
+npm run typecheck   # erreurs TypeScript
+npm run build       # compilation, puis analyse marketplace
+`}</Code>
+      <p>
+        <C>npm run build</C> rejoue <strong>exactement l’analyse de la marketplace</strong> : format du paquet, manifeste, code, permissions,
+        sécurité et présentation. Les erreurs (<C>✖</C>) bloqueraient l’envoi ; les avertissements (<C>!</C>) sont signalés au relecteur.
+        Deux avertissements sont normaux pendant le développement : le paquet n’est pas signé (NOVALABS le signe à la validation) et la capture
+        d’écran manque tant que vous ne l’avez pas ajoutée.
+      </p>
+      <p>
+        Pour analyser à nouveau un paquet sans recompiler : <C>npx snapify check dist/&lt;id&gt;-&lt;version&gt;.snapmod</C>. Le détail de chaque
+        contrôle est décrit dans <a href="/docs/securite#analyse-automatique">l’analyse automatique</a>.
+      </p>
+
+      <H2>2. Sur un site Snapify de test</H2>
+      <p>
+        Les paquets non signés ne s’installent que sur un site en <strong>mode développeur</strong>. Il vous faut une installation Snapify que
+        vous administrez (par exemple une copie de test de votre licence Snapify), jamais le site d’un client en production.
+      </p>
+      <Steps
+        items={[
+          {
+            title: 'Activer le mode développeur',
+            body: (
+              <>
+                Ajoutez <C>SNAPIFY_MODULES_DEV_MODE=true</C> au fichier <C>.env</C> du site, puis redémarrez-le. L’administration affiche alors
+                l’alerte « Mode développeur actif ».
+              </>
+            ),
+          },
+          {
+            title: 'Importer le paquet',
+            body: (
+              <>
+                Module : <strong>Administration › Modules › Importer un module</strong>. Thème : <strong>Apparence › Thèmes › Importer un thème</strong>.
+                L’écran d’installation affiche les permissions demandées et l’état « non signé, mode développeur ».
+              </>
+            ),
+          },
+          {
+            title: 'Activer et régler',
+            body: 'Activez le module (ou prévisualisez le thème avant de l’activer), puis remplissez ses réglages.',
+          },
+          {
+            title: 'Itérer',
+            body: (
+              <>
+                Après chaque <C>npm run build</C>, importez à nouveau le fichier : à version égale, l’administration propose de le{' '}
+                <strong>réinstaller</strong> en conservant ses réglages et ses données.
+              </>
+            ),
+          },
+        ]}
+      />
+      <H3>Que vérifier</H3>
+      <ul>
+        <li>Le rendu sur mobile et sur ordinateur, avec les thèmes officiels (SidiBou, Mahdia, Dogga) pour un module.</li>
+        <li>
+          L’aperçu de l’éditeur de pages : <C>isPreview</C> y vaut <C>true</C>, aucune action réelle ne doit partir (envoi de formulaire,
+          appel payant).
+        </li>
+        <li>Les réglages : valeurs par défaut, champs vides, textes longs ; seuls les réglages <C>public</C> atteignent le navigateur.</li>
+        <li>Les pages d’administration et les routes serveur avec un compte qui n’est pas super-administrateur.</li>
+        <li>
+          Les erreurs serveur : un module qui échoue au démarrage est signalé sur sa page dans l’administration, avec le message de l’erreur.
+        </li>
+      </ul>
+      <Note tone="warn" title="Jamais en production">
+        Le mode développeur accepte n’importe quel paquet non signé. Désactivez-le (supprimez la variable et redémarrez) dès la fin des tests.
+      </Note>
+
+      <H2>3. Pendant la revue</H2>
+      <p>
+        Sans installation Snapify, l’analyse locale reste votre filet de sécurité : envoyez ensuite le paquet depuis votre{' '}
+        <Link to="/docs/publier">espace vendeur</Link>. NOVALABS installe chaque version soumise sur un site de test, la relit et la teste
+        avant de la signer. En cas de refus, la raison est indiquée : corrigez, augmentez la version si nécessaire, puis soumettez à nouveau.
+      </p>
+      <div className="flex flex-wrap gap-3 pt-2">
+        <NextLink to="/docs/securite" label="Sécurité et revue" />
+        <NextLink to="/docs/publier" label="Publier sur la marketplace" />
+      </div>
+    </>
+  );
+}
+
+function Packages() {
+  return (
+    <>
+      <p>
+        L’outil <C>snapify</C> du <Link to="/docs/kit-developpeur">kit développeur</Link> compile les sources (React fourni par le site,
+        Tailwind compilé et limité au module), calcule l’empreinte de chaque fichier et produit un paquet <C>.snapmod</C> ou{' '}
+        <C>.snaptheme</C>, puis l’analyse comme la marketplace.
+      </p>
+      <Code lang="bash">{`
+# Depuis la racine du projet : paquet dans dist/, puis analyse
+npx snapify build
+
+# Dossier de sortie personnalisé
+npx snapify build . --out paquets
+
+# Analyser à nouveau un paquet, ou vérifier la signature d’un paquet reçu
+npx snapify check dist/monagence.mon-theme-1.0.0.snaptheme
+npx snapify verify monagence.mon-theme-1.0.0.snaptheme
+`}</Code>
+      <H2>Format</H2>
+      <p>Un paquet est un JSON compressé en gzip :</p>
+      <Code lang="json">{`
+{
+  "format": "snapmod/1",
+  "manifest": {
+    "…": "manifeste",
+    "entries": { "public": "public.js", "server": "server.mjs", "admin": "admin.js" },
+    "styles": "public.css",
+    "files": { "public.js": { "sha256": "…", "size": 1234 } },
+    "builtAt": "2026-10-15T08:00:00.000Z"
+  },
+  "files": { "public.js": "<base64>", "server.mjs": "<base64>" },
+  "signature": { "alg": "ed25519", "kid": "novalabs-2026", "value": "<base64>" },
+  "license": "SNAPIFY-LIC-…"
+}
+`}</Code>
+      <ul>
+        <li>
+          Fichiers autorisés : <C>public.js</C>, <C>public.css</C>, <C>server.mjs</C>, <C>admin.js</C>, <C>admin.css</C>, <C>README.md</C>{' '}
+          et la capture d’écran.
+        </li>
+        <li>Taille maximale : 20 Mo compressé, 40 Mo décompressé.</li>
+        <li>
+          La signature Ed25519 porte sur le manifeste, qui contient l’empreinte SHA-256 de chaque fichier : modifier un seul octet invalide le
+          paquet.
+        </li>
+      </ul>
+      <H2>Signature</H2>
+      <p>
+        Les sites en production n’installent que des paquets signés par une clé de confiance NOVALABS. C’est NOVALABS qui signe les versions
+        validées lors de la revue : vous n’avez pas à gérer de clé.
+      </p>
+      <H2>Licences</H2>
+      <p>
+        Un module gratuit signé embarque une licence valable sur tous les domaines. Un module payant demande une clé de licence (
+        <C>SNAPIFY-LIC-…</C>) liée au module, au client et à ses domaines (<C>exemple.tn</C>, <C>*.exemple.tn</C>), avec une date
+        d’expiration facultative. Elle est vérifiée hors ligne à l’installation, au démarrage puis toutes les 10 minutes ; <C>localhost</C> est
+        toujours accepté.
+      </p>
+    </>
+  );
+}
+
+function Security() {
+  return (
+    <>
+      <p>
+        Les extensions s’exécutent chez des clients qui ne lisent pas leur code. Le modèle de sécurité de Snapify repose sur des contrôles
+        automatiques et sur la revue de NOVALABS.
+      </p>
+      <Table
+        head={['Contrôle', 'Moment']}
+        rows={[
+          ['Signature du manifeste et empreinte de chaque fichier', 'Import, téléchargement, chaque démarrage, chaque activation'],
+          [<>Compatibilité de l’API (<C>engines.snapify</C>)</>, 'Installation et démarrage'],
+          ['Licence : signature, module, domaine, expiration', 'Installation, saisie de clé, démarrage, toutes les 10 minutes'],
+          ['Permissions du contexte serveur', 'À chaque appel'],
+          [<>Réglages validés ; seuls les réglages <C>public</C> atteignent le navigateur</>, 'Enregistrement et diffusion'],
+          [<>Fichiers servis depuis la copie vérifiée ; <C>server.mjs</C> jamais exposé</>, 'Chaque requête'],
+        ]}
+      />
+      <p>
+        Une extension dont un contrôle échoue est <strong>bloquée</strong> (non chargée, routes désactivées) et signalée dans l’administration
+        avec la raison. Une réinstallation depuis la marketplace la répare en conservant ses réglages.
+      </p>
+      <Note tone="warn" title="Ce n’est pas un bac à sable">
+        Le code serveur s’exécute dans le processus Node du site. Les permissions encadrent l’API fournie, mais un code malveillant pourrait
+        importer directement des modules Node : c’est pourquoi chaque version publiée est relue et signée par NOVALABS.
+      </Note>
+      <H2 id="analyse-automatique">Analyse automatique du paquet</H2>
+      <p>
+        À chaque import dans l’espace vendeur, le paquet est analysé <strong>sans exécuter son code</strong>. Le rapport classe les contrôles
+        par rubrique ; une erreur bloque la création du produit ou de la version, un avertissement est signalé à la revue.
+      </p>
+      <Table
+        head={['Rubrique', 'Refusé (erreur)', 'Signalé (avertissement)']}
+        rows={[
+          ['Paquet', 'Format illisible, fichier altéré, signature NOVALABS qui ne correspond plus, licence invalide', 'Paquet non signé (NOVALABS signe la version validée)'],
+          ['Manifeste', <>Type incorrect, <C>engines.snapify</C> incompatible avec l’API {API_VERSION}</>, <><C>engines</C> à <C>*</C></>],
+          ['Code', <>Erreur de syntaxe, pas d’export par défaut, <C>import()</C> ou <C>require</C>, dépendance non incluse dans le bundle, module Node interdit (<C>fs</C>, <C>child_process</C>, <C>net</C>, <C>http</C>…)</>, 'Bundle très lourd'],
+          ['Permissions', <>Appel <C>ctx</C> sans la permission correspondante (<C>ctx.db</C> sans <C>database</C>, <C>ctx.env('X')</C> sans <C>env:X</C>…)</>, <>Permission déclarée mais inutilisée, hôte <C>net:</C> non déclaré</>],
+          ['Sécurité', <><C>process.env</C>, <C>fetch</C> direct, <C>eval</C>, accès aux internes du CMS, CSS hors du conteneur du module</>, <><C>eval</C> ou <C>document.cookie</C> côté navigateur, <C>@import</C> distant</>],
+          ['Présentation', 'Réglage public qui ressemble à un secret, capture dont le contenu ne correspond pas à l’extension', 'README, capture ou description absents ; capture < 800 × 450'],
+          ['Marketplace', <>Préfixe <C>novalabs.</C> ou <C>snapify.</C>, identifiant d’un autre éditeur, mise à jour avec un autre <C>id</C> ou une version non supérieure</>, '—'],
+        ]}
+      />
+      <p>
+        Le serveur utilise exactement la même analyse : on ne peut pas la contourner en appelant l’API directement.
+      </p>
+      <H2>Checklist avant de soumettre</H2>
+      <ul>
+        <li>Permissions minimales et justifiées ; aucun accès réseau vers un hôte non déclaré.</li>
+        <li>Aucun secret dans les réglages publics ni dans le bundle navigateur.</li>
+        <li>Entrées validées côté serveur (longueurs, formats) et erreurs renvoyées avec <C>ctx.error()</C>.</li>
+        <li>Pas d’import de modules Node (<C>fs</C>, <C>child_process</C>…), pas de code obfusqué.</li>
+        <li>Rendu testé sur mobile, dans l’aperçu de l’éditeur et avec les thèmes officiels.</li>
+      </ul>
+    </>
+  );
+}
+
+function Publish() {
+  const s = useMarketplaceSettings();
+  const fee = s?.developerFeeLabel || '—';
+  const commission = s ? `${Math.round(s.commissionBps / 100)} %` : '—';
+  return (
+    <>
+      <p>
+        La <a href={MARKETPLACE_URL}>marketplace Snapify</a> distribue vos modules et thèmes à tous les sites Snapify. Les clients les
+        installent en un clic depuis leur administration.
+      </p>
+      <div className="grid gap-3 sm:grid-cols-2">
+        <div className="rounded-xl border border-slate-200 p-4">
+          <div className="text-xs font-semibold uppercase tracking-wide text-slate-500">Inscription développeur</div>
+          <div className="mt-1 text-2xl font-bold text-navy">{fee}</div>
+          <div className="text-sm text-slate-500">paiement unique via Flouci</div>
+        </div>
+        <div className="rounded-xl border border-slate-200 p-4">
+          <div className="text-xs font-semibold uppercase tracking-wide text-slate-500">Commission marketplace</div>
+          <div className="mt-1 text-2xl font-bold text-navy">{commission}</div>
+          <div className="text-sm text-slate-500">sur chaque vente d’une extension payante</div>
+        </div>
+      </div>
+      <H2>Étapes</H2>
+      <Steps
+        items={[
+          {
+            title: 'Créer un compte',
+            body: (
+              <>
+                Sur <a href={`${MARKETPLACE_URL}/register`}>marketplace.snapify.tn</a>. Le même compte sert pour la Community.
+              </>
+            ),
+          },
+          {
+            title: 'Devenir développeur',
+            body: (
+              <>
+                Depuis <a href={`${MARKETPLACE_URL}/developer`}>la page Développeurs</a>, renseignez votre nom d’éditeur et réglez l’inscription.
+                Votre espace vendeur s’ouvre aussitôt le paiement confirmé.
+              </>
+            ),
+          },
+          {
+            title: 'Importer votre paquet',
+            body: (
+              <>
+                Dans l’espace vendeur, déposez le <C>.snapmod</C> ou <C>.snaptheme</C>. Le paquet est analysé sans être exécuté (voir{' '}
+                <a href="/docs/securite#analyse-automatique">l’analyse automatique</a>) : tant qu’une erreur subsiste, le produit ne peut pas être
+                créé. Il est ensuite créé en brouillon à partir du manifeste.
+              </>
+            ),
+          },
+          {
+            title: 'Compléter la fiche',
+            body: 'Nom, descriptions courte et longue, catégorie, prix, icône et jusqu’à 8 captures d’écran.',
+          },
+          {
+            title: 'Soumettre pour review',
+            body: 'NOVALABS relit le code et le teste. Le produit est publié, ou refusé avec une raison : corrigez puis soumettez à nouveau.',
+          },
+          {
+            title: 'Publier des mises à jour',
+            body: (
+              <>
+                Importez une nouvelle version avec son changelog. Le même <C>id</C> et une <C>version</C> supérieure sont obligatoires ; les
+                sites clients la proposent comme mise à jour.
+              </>
+            ),
+          },
+        ]}
+      />
+      <H2>Revenus</H2>
+      <p>
+        L’espace vendeur affiche vos ventes, le montant brut, la commission et votre revenu net. Vous demandez vos virements depuis ce même
+        espace.
+      </p>
+      <H2>Bonnes fiches produit</H2>
+      <ul>
+        <li>Une couverture 1280 × 720 lisible en petit : le bénéfice principal en une phrase.</li>
+        <li>Des captures réelles : le rendu sur le site, puis les pages d’administration.</li>
+        <li>Une description qui liste ce que fait le module, les permissions demandées et pourquoi.</li>
+        <li>Un changelog clair pour chaque version.</li>
+      </ul>
+      <div className="flex flex-wrap gap-3 pt-2">
+        <a
+          href={`${MARKETPLACE_URL}/developer`}
+          className="inline-flex items-center gap-2 rounded-lg bg-navy px-4 py-2.5 text-sm font-semibold text-white no-underline hover:bg-navy-2"
+        >
+          Devenir développeur
+        </a>
+        <a
+          href={`${MARKETPLACE_URL}/developer/dashboard`}
+          className="inline-flex items-center gap-2 rounded-lg border border-slate-200 px-4 py-2.5 text-sm font-semibold text-navy no-underline hover:border-brand"
+        >
+          Ouvrir mon espace vendeur
+        </a>
+      </div>
+    </>
+  );
+}
+
+/* ------------------------------------------------------------------ Référence */
+
+function Permissions() {
+  return (
+    <>
+      <p>Demandez uniquement les permissions nécessaires : elles sont affichées au client avant l’installation.</p>
+      <Table
+        head={['Permission', 'Accorde']}
+        rows={[
+          [<C>site:read</C>, <>Informations publiques du site (<C>ctx.site()</C>).</>],
+          [<C>storage</C>, <>Stockage clé/valeur propre au module (<C>ctx.storage</C>).</>],
+          [<C>database</C>, <>Collections d’enregistrements (<C>ctx.db</C>).</>],
+          [<C>files</C>, <>Images publiques sous <C>/uploads/modules/&lt;id&gt;/</C> (<C>ctx.files</C>, API 1.3).</>],
+          [<C>http:routes</C>, <>Routes publiques sous <C>/api/modules/&lt;id&gt;/</C>.</>],
+          [<C>http:cookies</C>, <>Lecture et dépôt de cookies <C>sm_*</C> (sessions de visiteurs).</>],
+          [<C>admin:routes</C>, <>Routes réservées à l’administration.</>],
+          [<C>mail:send</C>, 'Envoi d’e-mails via le SMTP du site.'],
+          [<C>env:NOM</C>, <>Lecture d’une variable d’environnement précise, ex. <C>env:GEMINI_API_KEY</C>.</>],
+          [<C>net:hôte</C>, <>Requêtes HTTPS vers cet hôte uniquement, ex. <C>net:api.openai.com</C>.</>],
+        ]}
+      />
+      <H2>Version de l’API</H2>
+      <p>
+        L’API actuelle est la <strong>{API_VERSION}</strong>. La permission <C>files</C> et <C>@snapify/sdk/image</C> demandent{' '}
+        <C>"engines": {'{ "snapify": "^1.3.0" }'}</C>.
+      </p>
+    </>
+  );
+}
+
+function Cli() {
+  return (
+    <>
+      <p>
+        L’outil <C>snapify</C> est fourni par le paquet npm <C>snapify-sdk</C> (<Link to="/docs/kit-developpeur">kit développeur</Link>). Dans un projet, lancez-le avec{' '}
+        <C>npx snapify</C> ou les scripts <C>npm run build</C> et <C>npm run typecheck</C>.
+      </p>
+      <Table
+        head={['Commande', 'Rôle']}
+        rows={[
+          [
+            <C>create [dossier]</C>,
+            <>
+              Crée un projet de module ; sans dossier, pose ses questions dans le terminal (c’est ce que lance <C>npm create snapify@latest</C>).
+              Options : <C>--theme</C> (thème), <C>--id editeur.nom</C>, <C>--name</C>, <C>--author</C>, <C>--email</C>.
+            </>,
+          ],
+          [
+            <C>build [dossier]</C>,
+            <>
+              Compile et empaquette, puis lance l’analyse marketplace. Options : <C>--out dossier</C> (<C>dist</C> par défaut),{' '}
+              <C>--no-check</C>.
+            </>,
+          ],
+          [<C>check &lt;paquet&gt;</C>, 'Analyse d’un paquet, identique à celle effectuée à l’envoi sur la marketplace.'],
+          [<C>verify &lt;paquet&gt;</C>, 'Contrôle format, manifeste, empreintes, signature NOVALABS et licence d’un paquet reçu.'],
+          [<C>--version</C>, 'Version du kit.'],
+        ]}
+      />
+      <p>
+        Toutes les commandes renvoient un code de sortie non nul en cas d’erreur : <C>npm run build</C> peut servir tel quel dans une
+        intégration continue.
+      </p>
+      <p>Exemple de sortie de <C>verify</C> pour un paquet téléchargé depuis la marketplace :</p>
+      <Code lang="text">{`
+Module Akhbar Urgent 1.0.0 (hamdiayari.akhbar-urgent) — Hamdi Ayari
+  Permissions : http:routes, admin:routes, database
+  Fichiers    : public.js, public.css, admin.js, admin.css, server.mjs, README.md, screenshot.jpg
+  Signature   : valide (NOVALABS, clé novalabs-local-2026)
+  Licence     : valide (free)
+`}</Code>
+      <H2>Variables de l’outil</H2>
+      <Table
+        head={['Variable', 'Effet']}
+        rows={[
+          [<C>NO_COLOR=1</C>, 'Sortie sans couleurs (journaux d’intégration continue).'],
+          [<C>SNAPIFY_DEBUG=1</C>, 'Affiche la pile d’appels complète en cas d’erreur de compilation.'],
+        ]}
+      />
+      <H2>Variables d’un site Snapify</H2>
+      <p>
+        À placer dans le fichier <C>.env</C> d’une installation Snapify, puis redémarrer le site (voir{' '}
+        <Link to="/docs/tester">Tester une extension</Link>).
+      </p>
+      <Table
+        head={['Variable', 'Effet']}
+        rows={[
+          [<C>SNAPIFY_MODULES_DEV_MODE=true</C>, 'Site de test : accepte les paquets non signés. Jamais en production.'],
+          [<C>MARKETPLACE_URL</C>, 'Catalogue lu par l’administration du site (HTTPS obligatoire).'],
+        ]}
+      />
+      <H2>Intégration continue</H2>
+      <Code lang="yaml" title=".github/workflows/snapify.yml">{`
+name: snapify
+on: [push, pull_request]
+jobs:
+  build:
+    runs-on: ubuntu-latest
+    steps:
+      - uses: actions/checkout@v4
+      - uses: actions/setup-node@v4
+        with: { node-version: 22 }
+      - run: npm ci
+      - run: npm run typecheck
+      # échoue si l’analyse marketplace trouve une erreur
+      - run: npm run build
+        env: { NO_COLOR: '1' }
+`}</Code>
+    </>
+  );
+}
+
+const EXAMPLES: { id: string; name: string; shows: string }[] = [
+  { id: 'novalabs.whatsapp', name: 'WhatsApp', shows: 'Module 100 % navigateur : emplacement floating, réglages publics, aucune permission.' },
+  { id: 'novalabs.ai-chat', name: 'Chat IA', shows: 'Route serveur, clé d’API lue avec env:, appels sortants avec net:.' },
+  { id: 'novalabs.calendar', name: 'Calendrier', shows: 'Pages (routes), deux widgets, collections, page d’administration.' },
+  { id: 'novalabs.ai-articles', name: 'Articles IA', shows: 'Module payant : administration riche, files, plusieurs hôtes net:.' },
+  { id: 'novalabs.shop', name: 'Boutique', shows: 'Catalogue produits, widgets, services publiés avec ctx.provide().' },
+  { id: 'novalabs.cart', name: 'Panier', shows: 'requires, emplacement header-actions, page /panier/.' },
+  { id: 'novalabs.checkout', name: 'Commande', shows: 'Cookies, e-mails, ctx.lock(), dépendance facultative avec uses.' },
+  { id: 'novalabs.customers', name: 'Espace client', shows: 'Sessions de visiteurs, photos de profil (files), e-mails.' },
+  { id: 'novalabs.sidibou', name: 'SidiBou (thème)', shows: 'Thème complet, options de personnalisation, rendu de tous les blocs.' },
+  { id: 'novalabs.mahdia', name: 'Mahdia (thème)', shows: 'Thème boutique : intégration des modules e-commerce.' },
+];
+
+function Examples() {
+  return (
+    <>
+      <p>Les extensions officielles NOVALABS couvrent toutes les possibilités du SDK. Chacune illustre un cas d’usage :</p>
+      <div className="grid gap-3 sm:grid-cols-2">
+        {EXAMPLES.map((e) => (
+          <a
+            key={e.id}
+            href={product(e.id)}
+            className="block rounded-xl border border-slate-200 p-4 no-underline transition hover:border-brand hover:shadow-sm"
+          >
+            <div className="font-semibold text-navy">{e.name}</div>
+            <div className="mt-0.5 font-mono text-xs text-slate-400">{e.id}</div>
+            <div className="mt-2 text-sm font-normal leading-relaxed text-slate-600">{e.shows}</div>
+          </a>
+        ))}
+      </div>
+    </>
+  );
+}
+
+/* ------------------------------------------------------------------ Index */
+
+export const SECTIONS = ['Démarrer', 'Modules', 'Thèmes', 'Distribution', 'Référence'] as const;
+
+export const PAGES: DocPage[] = [
+  { slug: 'introduction', section: 'Démarrer', title: 'Introduction', description: 'Modules, thèmes, SDK : ce que vous pouvez construire avec Snapify.', keywords: 'sdk concepts module theme kit', Body: Introduction },
+  { slug: 'kit-developpeur', section: 'Démarrer', title: 'Kit développeur', description: 'Installer le SDK depuis npm, créer un projet avec npm create snapify, téléchargement direct.', keywords: 'sdk installer telecharger npm npx create starter cli download snapify', Body: KitDownload },
+  { slug: 'demarrage-rapide', section: 'Démarrer', title: 'Premier module', description: 'Un module complet en cinq fichiers : manifeste, interface, serveur, construction.', keywords: 'quickstart tutoriel', Body: Quickstart },
+  { slug: 'modules/manifeste', section: 'Modules', title: 'Manifeste', description: 'Le fichier snapify.module.json : identité, permissions, emplacements, routes.', keywords: 'json id version engines icon screenshot widgets routes adminPages requires', Body: Manifest },
+  { slug: 'modules/reglages', section: 'Modules', title: 'Réglages', description: 'Champs générés dans l’administration, publics ou privés.', keywords: 'settings formulaire champs', Body: SettingsDoc },
+  { slug: 'modules/site-public', section: 'Modules', title: 'Site public', description: 'Emplacements, pages et widgets affichés aux visiteurs.', keywords: 'slots floating header-actions widget page react tailwind', Body: PublicSide },
+  { slug: 'modules/serveur', section: 'Modules', title: 'Serveur', description: 'Routes HTTP, cookies, e-mails et le contexte ctx.', keywords: 'api routes http ctx cookies mail fetch env', Body: ServerSide },
+  { slug: 'modules/base-de-donnees', section: 'Modules', title: 'Base de données', description: 'Collections d’enregistrements : insertion, filtres, recherche, tri.', keywords: 'database collection find insert', Body: Database },
+  { slug: 'modules/administration', section: 'Modules', title: 'Administration', description: 'Pages du back-office, composants et routes d’administration.', keywords: 'admin backoffice pages composants', Body: Admin },
+  { slug: 'modules/dependances', section: 'Modules', title: 'Dépendances', description: 'Faire coopérer plusieurs modules : requires, uses, services.', keywords: 'requires uses provide use services', Body: Dependencies },
+  { slug: 'themes/creer-un-theme', section: 'Thèmes', title: 'Créer un thème', description: 'Structure, contrat defineTheme, options et intégration des modules.', keywords: 'theme header footer layout usesnapify', Body: ThemeCreate },
+  { slug: 'themes/blocs', section: 'Thèmes', title: 'Rendu des blocs', description: 'Les 26 types de blocs de l’éditeur et leur typage.', keywords: 'blocks hero cta faq', Body: ThemeBlocks },
+  { slug: 'tester', section: 'Distribution', title: 'Tester une extension', description: 'Analyse locale, site Snapify de test en mode développeur, revue NOVALABS.', keywords: 'test tester mode developpeur dev mode importer reinstaller debug', Body: Testing },
+  { slug: 'paquets', section: 'Distribution', title: 'Paquets et licences', description: 'Construire et vérifier ; format .snapmod, signature et licences.', keywords: 'build snapmod snaptheme signature licence', Body: Packages },
+  { slug: 'securite', section: 'Distribution', title: 'Sécurité et revue', description: 'Contrôles automatiques et critères de la revue NOVALABS.', keywords: 'securite review', Body: Security },
+  { slug: 'publier', section: 'Distribution', title: 'Publier sur la marketplace', description: 'Inscription développeur, import du paquet, review, mises à jour, revenus.', keywords: 'marketplace vendre publier commission', Body: Publish },
+  { slug: 'reference/permissions', section: 'Référence', title: 'Permissions', description: 'Toutes les permissions et les versions de l’API.', keywords: 'permissions api version', Body: Permissions },
+  { slug: 'reference/cli', section: 'Référence', title: 'Outil en ligne de commande', description: 'Commandes create, build, check et verify.', keywords: 'cli npm npx commande snapify', Body: Cli },
+  { slug: 'reference/exemples', section: 'Référence', title: 'Exemples officiels', description: 'Les extensions NOVALABS et ce que chacune illustre.', keywords: 'exemples modules officiels', Body: Examples },
+];