Spécification : Sanity Visual Editing

Slice : Slice 1 (Page d’accueil)
Cycle : DOC → SPEC → CODE → TEST → INTÉG
Statut : SPEC

1. Objectif

Implémenter le Sanity Visual Editing (Presentation Tool + Stega) pour permettre aux collaborateurs de prévisualiser et modifier le contenu directement depuis le Studio, fonctionnant pour tous les types de pages (SSG et SSR).

2. Configuration technique

2.1. Configuration Sanity Studio

Fichier : apps/studio/sanity.config.ts

Plugin presentation tool :

import { presentationTool } from 'sanity/presentation'
import { defineLocations } from 'sanity/presentation'

export const resolve = {
  locations: {
    page: defineLocations({
      select: { title: 'title', slug: 'slug.current' },
      resolve: (doc) => ({
        locations: [
          { title: doc?.title || 'Untitled', href: doc?.slug?.current === '/' ? '/' : `/${doc?.slug?.current}` },
        ],
      }),
    }),
  },
}

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

2.2. Configuration Astro

Fichier : apps/web/astro.config.mjs

Activation Stega :

import sanity from '@sanity/astro'

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

Fichier : apps/web/src/layouts/MainLayout.astro

Rendu Visual Editing Overlay :

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

2.3. Gestion des variables d’environnement

Variables nécessaires :

SANITY_PROJECT_ID : Déjà configurée
SANITY_DATASET : Déjà configurée
SANITY_STUDIO_PREVIEW_URL : À ajouter (http://localhost:4321 en dev, URL prod en prod)
SANITY_API_READ_TOKEN : Pour la perspective previewDrafts

3. Structure des fichiers

3.1. Fichier resolve

Fichier : apps/studio/sanity/presentation/resolve.ts

Structure :

import { defineLocations, PresentationPluginOptions } from 'sanity/presentation'

export const resolve: PresentationPluginOptions['resolve'] = {
  locations: {
    page: defineLocations({
      select: { title: 'title', slug: 'slug.current' },
      resolve: (doc) => ({
        locations: [
          { title: doc?.title || 'Untitled', href: doc?.slug?.current === '/' ? '/' : `/${doc?.slug?.current}` },
        ],
      }),
    }),
  },
}

3.2. Nettoyage Stega

Fichier : apps/web/src/lib/stega.ts

Structure :

import { stegaClean } from '@sanity/client/stega'

export function cleanStega<T>(value: T): T {
  if (typeof value === 'string') {
    return stegaClean(value) as T
  }
  return value
}

4. Implémentation

4.1. Configuration Studio

Modifications :

Ajouter le plugin presentationTool
Créer le fichier sanity/presentation/resolve.ts
Configurer l’URL de preview selon l’environnement

4.2. Configuration Astro

Modifications :

Activer stega: true dans l’intégration Sanity
Vérifier que le client Sanity est configuré correctement

4.3. Utilisation des données

Composants :

Les champs texte contiennent des métadonnées Stega
Utiliser stegaClean pour les comparaisons et logiques
Ne pas nettoyer pour le rendu (nécessaire pour click-to-edit)

5. Comportement attendu

5.1. Mode Development

Comportement :

Studio accessible sur http://localhost:3333
Presentation tool rendu avec http://localhost:4321
Click-to-edit fonctionnel
Mises à jour en temps réel

5.2. Mode Production

Comportement :

Studio avec URL de production
Presentation tool rendu avec URL de production
Stega activé en production
Cache CDN activé

5.3. Pages SSG (index.astro)

Comportement :

Présentation tool fonctionne sur les pages prerendered
Stega encodé dans le HTML statique
Click-to-edit via metadata Stega

5.4. Pages SSR ([slug].astro)

Comportement :

Présentation tool fonctionne sur les pages SSR
Stega encodé dans le HTML généré
Click-to-edit via metadata Stega

6. Tests et validation

6.1. Tests de configuration

Commandes :

task dev:studio
task dev

Attendu :

Studio démarré avec plugin presentation tool
Bouton “Presentation” visible dans le Studio
Presentation tool rendu correctement

6.2. Tests de visual editing

Scénarios :

Ouvrir le Studio
Cliquer sur “Presentation”
Naviguer vers la page d’accueil
Modifier un champ dans le Studio
Vérifier la mise à jour en temps réel dans la Presentation tool
Tester le click-to-edit sur les éléments

6.3. Tests Stega

Commandes :

task build:web

Attendu :

Build réussi
HTML contient les métadonnées Stega
Pas d’erreurs liées à Stega

7. Intégration avec l’existant

7.1. Compatibilité avec index.astro

État actuel :

index.astro est prerendered (export const prerender = true)
Utilise getSanityClient() existant
Rendu PageBuilder

Modification requise :

Aucune modification logique
Stega activé via configuration Astro
Presentation tool fonctionnera sur la page prerendered

7.2. Compatibilité avec [slug].astro

État actuel :

[slug].astro est SSR (export const prerender = false)
Utilise getSanityClient() existant
Rendu PageBuilder

Modification requise :

Aucune modification logique
Stega activé via configuration Astro
Presentation tool fonctionnera

7.3. Compatibilité avec welcome.astro

État actuel :

welcome.astro est SSR
Utilise getSanityClient() avec mode preview

Modification requise :

Retirer la logique preview existante (bannière, cookie)
Stega remplacera cette logique
Présentation tool utilisé à la place

8. Nettoyage de l’approche précédente

8.1. Middleware Astro à supprimer

Fichier : apps/web/src/middleware.ts

Déjà supprimé

8.2. Middleware Cloudflare à conserver

Fichier : services/preview-middleware/src/index.ts

Garder pour l’API /api/preview utilisée par Studio
Garder pour l’API /api/exit-preview
Ce middleware reste nécessaire pour le lien Studio → Site

8.3. Bannières preview à supprimer

Fichiers :

Retirer toute logique de bannière preview des composants
Stega + Presentation tool remplacent cette approche

9. Problèmes potentiels et solutions

9.1. Presentation tool non visible

Problème : Plugin presentation tool non configuré

Solution :

Vérifier sanity.config.ts
Vérifier que le plugin est importé et configuré

9.2. Stega non fonctionnel

Problème : stega: true non activé

Solution :

Vérifier astro.config.mjs
Vérifier que stega: true est activé

9.3. Live Content API non fonctionnel

Problème : Mises à jour en temps réel ne fonctionnent pas

Solution :

Vérifier que le client Sanity est configuré pour Live Content API
Vérifier les variables d’environnement

10. Checklist de validation

Avant de passer à l’étape CODE :

Documentation Studio visual editing complète
Spécification technique complète
Compatibilité avec l’existant analysée
Nettoyage de l’approche précédente planifié
Tests définis
Problèmes potentiels identifiés

11. Approbation

Validation requise : Confirmer que la spécification peut passer à l’étape CODE.

12. Historique des modifications

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