Sanity Visual Editing

Objet : Sanity Visual Editing
Type : Configuration
Slice : Slice 1 (Page d’accueil)
Cycle : DOC → SPEC → CODE → TEST → INTÉG
Statut : DOC

---

1. Description et périmètre

1.1. Objectif

Le Sanity Visual Editing permet aux collaborateurs de prévisualiser et modifier le contenu directement depuis l’interface du Studio, avec un affichage “click-to-edit” et des modifications en temps réel.

1.2. Utilisation principale

• Prévisualisation des brouillons Sanity
• Édition visuelle click-to-edit
• Mise à jour en temps réel pendant l’édition
• Fonctionne pour tous les types de pages (SSG et SSR)

1.3. Périmètre concerné

• Type : Configuration Sanity Studio + intégration Astro
• Composants : sanity/presentation plugin, loaders @sanity/astro
• Pages : Page d’accueil, blog, et toutes les pages Sanity-backed
• Technologie : Stega (Content Source Maps), Live Content API

---

2. Contrats d’entrée

2.1. Configuration Studio

Entrée : Plugin sanity/presentation dans sanity.config.ts

Structure :

import { presentationTool } from 'sanity/presentation'
import { resolve } from '@/sanity/presentation/resolve'

export default defineConfig({
  plugins: [
    presentationTool({
      resolve,
      previewUrl: {
        initial: process.env.SANITY_STUDIO_PREVIEW_URL || 'http://localhost:4321',
        previewMode: {
          enable: '/api/draft-mode/enable',
        },
      },
    }),
  ],
})

Règles :

• URL de prévisualisation configurée pour dev et prod
• Mode draft activé via endpoint /api/draft-mode/enable
• Document locations définis pour navigation bidirectionnelle

2.2. Configuration Astro

Entrée : Loader @sanity/astro dans astro.config.mjs et <VisualEditing /> dans MainLayout.astro

Structure :

import sanity from '@sanity/astro'

export default defineConfig({
  integrations: [
    sanity({
      projectId: process.env.SANITY_PROJECT_ID,
      dataset: process.env.SANITY_DATASET,
      stega: {
        studioUrl: process.env.SANITY_STUDIO_PREVIEW_URL || 'http://localhost:3333',
      },
    }),
  ],
})

Composant Layout :

---
import { VisualEditing } from '@sanity/astro/visual-editing';
const visualEditingEnabled = !!Astro.cookies.get('sanity-perspective')?.value;
---
<VisualEditing enabled={visualEditingEnabled} />

Règles :

• Stega activé sur createClient dans loadQuery.ts quand visualEditingEnabled est vrai
• Composant <VisualEditing /> injecté dans le layout principal pour charger les overlays du Presentation Tool
• Perspective drafts activée via le cookie sanity-perspective

---

3. Contrats de sortie

3.1. Comportement Studio

Sortie : Interface de prévisualisation intégrée

Comportement :

• Bouton “Presentation” dans le Studio
• Rendu du site dans un iframe dans le Studio
• Navigation bidirectionnelle entre Studio et site
• Click-to-edit sur les éléments du site

3.2. Comportement Frontend

Sortie : Rendu des données Sanity avec metadata Stega

Comportement :

• Les champs texte contiennent des métadonnées invisibles
• Ces métadonnées permettent le click-to-edit
• Mises à jour en temps réel via Live Content API
• Présence d’indicateurs visuels en mode preview

---

4. Side effects

4.1. Impact sur le rendu

Effet : Les champs texte contiennent des métadonnées Stega

Impact :

• Les métadonnées sont invisibles visuellement
• Elles sont utilisées par le Presentation Tool
• Doivent être nettoyées avant utilisation logique (comparaisons, etc.)

4.2. Impact sur le cache

Effet : Mode preview désactive le cache

Impact :

• En mode preview : pas de cache, données live
• En mode production : cache CDN activé
• Nécessite de gérer le mode draft-mode/preview

---

5. Erreurs et gestion

5.1. Erreurs potentielles

Erreur	Cause probable	Solution
Stega corrompu	Mauvaise configuration sanity	Vérifier stega: true dans config
Presentation tool non visible	Plugin non configuré	Vérifier sanity.config.ts
Click-to-edit non fonctionnel	Resolve mal configuré	Vérifier document locations
Draft mode non activé	Endpoint manquant	Créer endpoint /api/draft-mode/enable

5.2. Fallbacks

Gestion des erreurs :

• Si Stega échoue : rendu normal sans click-to-edit
• Si Presentation tool échoue : utiliser open preview classique
• Si Live Content API échoue : requête standard Sanity

---

6. Architecture

6.1. Flux de données

Studio → Presentation Tool → Frontend Astro → Sanity Live API
      ↓                        ↓                  ↓
   Edit content          Render with Stega    Real-time updates
      ↓                        ↓                  ↓
   Click-to-edit        Metadata decoding    Automatic refresh

6.2. Composants

Studio :

• sanity/presentation plugin
• Document locations pour navigation
• Resolve function pour mapping routes

Frontend :

• Loader @sanity/astro avec stega
• Endpoint draft-mode/enable
• Composants compatibles Stega

---

7. Sécurité

7.1. Token gestion

Règles :

• Token de lecture Sanity requis pour preview
• Token injecté via variable d’environnement
• Jamais exposé dans le code client

7.2. Draft mode protection

Règles :

• Endpoint draft-mode protégé (optionnel)
• Secret Sanity utilisé pour validation
• Mode preview accessible uniquement aux auteurs

---

8. Checklist de validation

Avant de considérer le Visual Editing comme terminé :

• Documentation Studio visual editing
• Plugin presentation configuré
• Document locations définis
• Loader Astro configuré avec stega
• Endpoint draft-mode créé
• Click-to-edit fonctionnel
• Live Content API testé
• Mode preview pour pages SSG testé
• Mode preview pour pages SSR testé

---

9. Approbation

Validation requise : Confirmer que la documentation du Visual Editing peut passer à l’étape SPEC.

---

10. Historique des modifications

Date	Version	Description	Auteur
2026-09-17	1.0	Création initiale	Devin