Fondations

07 — Domaines et sites

Statut : en cours · Phase : P2 · Mis à jour : 02/11/2026.

1. Logique

• recit.dev est la vitrine de la promesse globale : une source, tous les formats. Il montre ce qui marche aujourd'hui.
• vision.recit.dev (décidé le 25/10/2026) dit pourquoi et où ça va : le problème, la thèse, les principes et leur prix, l'ordre des phases, et ce que Récit refuse de faire. C'est le pendant éditorial de recit.dev, pas une seconde vitrine : il ne décrit aucune fonctionnalité comme acquise et ne documente rien. Il n'apparaît pas dans le sélecteur de sites de l'en-tête (comme recit.dev), seulement dans le pied de page.
• docs.recit.dev contient toute la documentation, pour tous les formats.
• Un sous-domaine par format, nommé par le mot que l'utilisateur cherche : presentation, motion, report, webtoon, book, roadmap, calendar, story. C'est la vitrine du format : promesse, galerie jouable, gabarits. Les neuf formats de la 1.0 font partie de la vision (docs est porté par docs.recit.dev). Chaque site ouvre à la sortie de son format (P2, P4, P6, P7, P8, P9, P10, P11). Les sites des plans 10 à 14 (ordre accepté le 24/10) ouvrent après la 1.0 (P13 à P16).
• Sites d'outil (acceptés le 24/10/2026, plans 10 et 14) : à côté de www, docs et components, un site peut présenter un outil ou un bloc qui n'est pas un format (form.recit.dev tant qu'il n'existe pas de format form, ai.recit.dev). Mêmes règles : vitrine écrite avec Récit, aucune doc propre.
• Chaque site existe dans toutes les langues configurées (/fr/…), avec un sélecteur de langue (voir 09-langues-et-json.md §6).

Règle anti-doublon : un sous-domaine de format ne contient pas de documentation. Chaque « comment faire » renvoie vers docs.recit.dev/<format>/…. On évite ainsi deux docs qui divergent.

Chaque site est construit avec Récit (Le framework de sites + @recit/site-stories) : on mange notre propre cuisine. La vitrine d'un format est elle-même écrite dans ce format. Le haut de presentation.recit.dev est un deck jouable, celui de motion.recit.dev une vidéo jouable, celui de report.recit.dev un rapport, celui de webtoon.recit.dev un épisode, celui de book.recit.dev un livre, celui de roadmap.recit.dev la roadmap de Récit elle-même, celui de calendar.recit.dev un vrai calendrier (sorties, meetups), celui de story.recit.dev une story.

2. Carte des domaines

Alias (redirections 301, aucun contenu propre)

Règle des alias (tranchée le 24/10, plans 10 à 14, question 22 de 06-roadmap.md) : le domaine principal porte le nom anglais ; les mots français du backlog et le nom technique du format deviennent des alias 301, jamais des sites.

Doc des blocs transverses (accepté) : docs.recit.dev/components/<bloc> pour form, pixel, textcard, map et term ; le contrat des formulaires sous la section API.

3. motion, et video en simple redirection

Décision (24/10/2026) : on garde motion. La vidéo n'est pas un format à part, c'est une sortie du format motion.

• Un seul site, motion.recit.dev, avec une section /video (export MP4, formats sociaux, rendu en CI).
• video.recit.dev est une simple redirection 301 vers motion.recit.dev/video. Il n'y a ni site ni package video.

4. Architecture des sites

Code
sites/www            ┐
sites/vision         │
sites/docs           ├─ site + @recit/site-stories + @recit/site-kit
sites/presentation   │    • createSiteConfig({ site: "presentation" }) : en-tête, pied, logo, thème
sites/motion         │    • stories/ : récits de la galerie (section publish: du recit.config)
sites/report         │
sites/webtoon        │
sites/book           │
sites/roadmap        │
sites/calendar       │
sites/story          │
sites/components     │
sites/form           │  ← acceptés (plans 10, 12, 13, 14), après la 1.0
sites/directory      │
sites/maps           │
sites/ai             ┘

Arborescence de docs.recit.dev (gabarit)

Décidé le 27/10/2026 (audit DO-5). La règle : l'onglet Documentation ne contient que ce que tout format lit. Ce qui n'est vrai que d'un format descend sous Formats › <Format>. Sans cela, les pages motion auraient dû disputer l'onglet générique au deck, qui l'occupait seul.

Code
Documentation                    Formats
├─ Getting started               ├─ formats/overview
│  ├─ quickstart                 ├─ Deck  → formats/deck/overview
│  └─ tutorial                   │  ├─ layouts
├─ Writing                       │  ├─ slide-options
│  ├─ overview                   │  ├─ density-rules
│  ├─ scenes      ← le séparateur│  ├─ presenter-console
│  ├─ code-math-diagrams         │  ├─ smartphone-remote
│  ├─ notes-and-steps            │  └─ exporting
│  └─ mdx                        └─ Motion → formats/motion
├─ Configuration                    └─ (les pages motion viennent ici)
│  ├─ overview                   Theme
│  └─ recit-config               └─ (inchangé)
├─ Integrations
│  └─ site
└─ Reference
   ├─ cli
   ├─ accessibility
   └─ architecture

Un nouveau format ouvre une catégorie sous Formats, avec sa page overview en link:. Il n'ajoute rien à l'onglet Documentation, sauf si la syntaxe devient commune — auquel cas la page commune est réécrite dans le vocabulaire commun, comme writing/slides est devenu writing/scenes. Toute page déplacée garde son ancienne adresse par un redirects: du recit.config.ts.

• @recit/site-kit (privé) :
  • en-tête commun avec le sélecteur de sites (Récit ▸ Presentation · Motion · Report · Webtoon · Book · Roadmap · Calendar · Story · Docs, puis Form, Directory, Maps et AI à leur ouverture) et le sélecteur de langue ;
  • pied de page avec les mentions de NOTICE.md, logos de brand/, tokens Q07 ;
  • createSiteConfig(), qui renvoie la base du recit.config.ts de chaque site (chaque site n'a qu'un recit.config.ts, plus de recit.config.tsx) ;
  • table SITES, de type { label, url, port } (l'URL locale est dérivée du port ; l'icône du format est prévue, pas encore dans le type), seule source des liens inter-sites.
• Récits partagés : les galeries réutilisent examples/*. sites/presentation lit examples/deck-* par publish.decks de son recit.config.ts (defineConfig injecte les plugins), ce qui évite de copier les sources. Les démos de la doc pointent vers les mêmes slugs.
• Liens inter-sites : jamais en dur. On passe par SITES[...], qui bascule automatiquement sur les ports locaux en dev.
• Ports locaux : www 3000, docs 3001, presentation 3002, motion 3003 (preview e2e 4303), components 3010 et vision 3015 (preview e2e 4315) sont déjà dans packages/tools/site-kit/src/sites.ts. Réservés ici et ajoutés à sites.ts à la création du site : report 3004, webtoon 3005, book 3006, roadmap 3007, calendar 3008, story 3009, puis (plans 10 à 14, acceptés le 24/10) form 3011, directory 3012, maps 3013, ai 3014. Cette table est la seule attribution : SiteId et SITES la reprennent à la création de chaque site. Script racine prévu, pas encore ajouté : recit:sites:dev lance tous les sites ouverts (nx run-many -t dev -p 'sites/*').
• Recherche : Pagefind par site. docs.recit.dev indexe aussi les slides de ses démos (#slide-N). Une recherche transverse est hors périmètre pour l'instant.
• SEO : canonical vers le domaine principal (jamais vers un alias), Open Graph par site (déclinaisons og-card avec l'icône du format), sitemap.xml par site.
• Couleur par site (décision du 25/10/2026, table complète dans 01-assets.md §1) : recit.dev en noir et blanc, graphite pour docs, components et les sites d'outil (form, ai), et une teinte par format — deck bleu, motion violet, report sarcelle, webtoon orange, book ambre, roadmap vert, calendar rouge, story magenta, maps indigo. createSiteConfig() pose les tokens --primary clair et sombre de la teinte du site depuis brand/boards/colors/palette.json ; le logo, le favicon et la carte OG du site sont ceux de sa teinte. Un site n'écrit jamais une couleur en dur.

Composants habituels de chaque site de format

Tous les sites de format ont la même structure. Ces composants viennent de @recit/site-kit, et ils sont alimentés par les composants du format (08-formats.md) :

sites/www reprend SiteHeader, FormatGallery (tous formats), une grille des neuf formats avec leur statut, et la démo « une source, plusieurs rendus » (deck, motion, stories, report).

5. Déploiement : Vercel

Décision (24/10/2026) : tout est hébergé sur Vercel. Un projet Vercel par site, dans une équipe Vercel recit.

• DNS chez le registrar de recit.dev : CNAME de chaque sous-domaine vers Vercel (cname.vercel-dns.com), apex recit.dev en A/ALIAS selon le registrar. Les alias (www, deck, slides, video, toon, stories, agenda, events, puis, acceptés le 24/10, glossary, glossaire, annuaire, cartes, atlas, scenario) sont déclarés comme domaines de redirection 301 dans le projet cible.
• Chaque projet a un Ignored Build Step (npx nx-ignore <projet> ou nx show projects --affected), pour ne reconstruire que les sites touchés. Prévisualisation par PR.
• Pas de rendu lourd sur Vercel : Chrome, Remotion, Paged.js et sharp tournent en CI. Vercel ne sert que du statique (les sites sont prérendus).
• À décider (15-export-pdf.md, question 8) : comment les fichiers générés en CI (PDF, EPUB, MP4, tranches, PNG) arrivent sur Vercel, par un déploiement « prebuilt » depuis GitHub Actions ou par un stockage statique séparé. C'est un prérequis pour qu'un PDF se télécharge sur report.recit.dev, webtoon.recit.dev ou book.recit.dev. Les fichiers et exports.json sont écrits dans le dossier de sortie du site (dist/), sans second build.
• recit.dev est en .dev, donc HSTS préchargé et HTTPS obligatoire (certificats gérés par Vercel).
• Le vercel.json du docs/ d'upstream sert de modèle (en-têtes, redirections), un par site.

6. Actions

• P0 : acheter recit.dev, créer l'équipe Vercel recit.
• P2 : packages/tools/site-kit, puis sites/docs (contenu de presentation-engine/docs/pages/documentation, components et theme).
• P2 : sites/presentation (contenu de presentation-engine/docs/pages/demos + galerie), puis sites/www.
• P2 : DNS, projets Vercel recit-www, recit-docs, recit-presentation, redirections www, deck, slides.
• P4 : sites/motion (25/10 : hero, galerie, deck → vidéo, /video, e2e).
• P4 : projet Vercel recit-motion, redirection video.recit.dev → motion.recit.dev/video, job CI qui rend les MP4 de /video.
• P6 : sites/report, projet recit-report.
• P7 : sites/webtoon, projet recit-webtoon, redirection toon.recit.dev.
• P8 : sites/book, projet recit-book.
• P9 : sites/roadmap, projet recit-roadmap.
• P10 : sites/calendar, projet recit-calendar, redirections agenda et events.
• P11 : sites/story, projet recit-story, redirection stories.
• Accepté (24/10), P13 : sites/form, projet recit-form (10-formulaires.md).
• Accepté (24/10), P14 : sites/directory, projet recit-directory, redirections glossary, glossaire, annuaire (12-glossaire-annuaire.md).
• Accepté (24/10), P15 : sites/maps, projet recit-maps, redirections cartes, atlas (13-cartes.md).
• Accepté (24/10), P16 : sites/ai, projet recit-ai, redirection scenario (14-ia-scenario.md).
• Sur recit.dev, chaque format apparaît dès P2 avec son icône et son statut (« disponible », ou « P6 » … « P11 »). Le lien pointe vers son site dès l'ouverture.