Sanity Visual Editing

Documentation technique

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 Studio1/2

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',
        },
      },
    }),
  ],
})

2.1. Configuration Studio2/2

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 Astro1/4

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

Structure :

2.2. Configuration Astro2/4

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',
      },
    }),
  ],
})

2.2. Configuration Astro3/4

Composant Layout :

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

2.2. Configuration Astro4/4

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